Quick Start - cURL & HTTP APIs

Get started with Importly using simple HTTP requests. Perfect for testing, debugging, or integrating with any programming language.

1. Get Your API Key

1. Create an Account at Importly.io
2. Find your API Key via the api key page
3. Keep it secure—treat it like a password!

2. Your First Import

The main functionality of Importly is to import and process media from URLs:

bash
Copy
1curl -X POST "https://api.importly.io/import" \
2     -H "Authorization: Bearer YOUR_API_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{
5       "url": "https://example.com/your-media-url",
6       "videoQuality": "1080p",
7       "webhookUrl": "https://your-domain.com/webhook"
8     }'

Expected Response:

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "queued",
6    "message": "Media import has been queued. You will receive a webhook when it's complete."
7  }
8}

3. Check Import Status

bash
Copy
1curl -X GET "https://api.importly.io/import/status?id=abc123" \
2     -H "Authorization: Bearer YOUR_API_KEY"

Expected Response (when completed):

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "completed",
6    "result": {
7      "mediaUrl": "https://storage.importly.io/abc123/video.mp4",
8      "title": "Your Media Title",
9      "duration": 300,
10      "creditsUsed": 53,
11      "fileSizeBytes": 52428800,
12      "filename": "video.mp4"
13    },
14    "startedAt": "2025-09-14T10:00:00Z",
15    "completedAt": "2025-09-14T10:01:00Z"
16  }
17}

4. Get Metadata Only

If you want to retrieve media details without downloading:

bash
Copy
1curl -X GET "https://api.importly.io/metadata?url=https://example.com/your-media-url" \
2     -H "Authorization: Bearer YOUR_API_KEY"

Expected Response:

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "xyz789",
5    "status": "queued",
6    "message": "Metadata request queued."
7  }
8}

Check Metadata Status

bash
Copy
1curl -X GET "https://api.importly.io/metadata/status?id=xyz789" \
2     -H "Authorization: Bearer YOUR_API_KEY"

Expected Response (when completed):

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "xyz789",
5    "status": "completed",
6    "result": {
7      "title": "Sample Video Title",
8      "duration": 300,
9      "thumbnailUrl": "https://storage.importly.io/xyz789/thumbnail.jpg",
10      "description": "Video description",
11      "uploader": "Channel Name",
12      "uploadDate": "2025-09-01",
13      "viewCount": 1000000,
14      "availableQualities": ["480p", "720p", "1080p"],
15      "creditsRequired": 53
16    },
17    "startedAt": "2025-09-14T10:00:00Z",
18    "completedAt": "2025-09-14T10:00:15Z"
19  }
20}

5. Import Options

The import endpoint supports several customization options:

bash
Copy
1curl -X POST "https://api.importly.io/import" \
2     -H "Authorization: Bearer YOUR_API_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{
5       "url": "https://example.com/your-media-url",
6       "includeVideo": true,
7       "includeAudio": true,
8       "videoQuality": "1080p",
9       "audioQuality": "high",
10       "webhookUrl": "https://your-domain.com/webhook",
11       "formatSelector": "best[height<=1080]"
12     }'

Available Options:

| Parameter | Type | Default | Description | | ---------------- | ------- | ------------ | -------------------------------------------------------------------------- | | url | string | required | The media URL to import | | includeVideo | boolean | true | Whether to include video | | includeAudio | boolean | true | Whether to include audio | | videoQuality | string | "720p" | Desired video quality (480p, 720p, 1080p, 1440p, 2160p) | | audioQuality | string | "medium" | Desired audio quality (low, medium, high) | | webhookUrl | string | null | URL to receive completion notification | | formatSelector | string | null | Advanced format selection (see format selectors) |

6. Error Handling

Importly returns standard HTTP status codes and detailed error messages:

Authentication Error (401)

bash
Copy
1curl -X POST "https://api.importly.io/import" \
2     -H "Authorization: Bearer INVALID_KEY" \
3     -H "Content-Type: application/json" \
4     -d '{"url": "https://example.com/video"}'

Response:

json
Copy
1{
2  "success": false,
3  "error": "Invalid API key",
4  "code": "INVALID_AUTH"
5}

Insufficient Credits (402)

json
Copy
1{
2  "success": false,
3  "error": "Insufficient credits. Required: 50, Available: 25",
4  "code": "INSUFFICIENT_CREDITS"
5}

Rate Limiting (429)

json
Copy
1{
2  "success": false,
3  "error": "Rate limit exceeded. Try again in 60 seconds.",
4  "code": "RATE_LIMITED",
5  "retryAfter": 60
6}

Bad Request (400)

json
Copy
1{
2  "success": false,
3  "error": "Invalid URL format",
4  "code": "INVALID_URL"
5}

7. Webhooks Setup

To receive automatic notifications when imports complete, set up a webhook endpoint:

Example Webhook Request

When your import completes, Importly will send a POST request to your webhook URL:

bash
Copy
1# What Importly sends to your webhook URL
2POST https://your-domain.com/webhook
3Content-Type: application/json
4
5{
6  "type": "import.completed",
7  "data": {
8    "jobId": "abc123",
9    "status": "completed",
10    "result": {
11      "mediaUrl": "https://storage.importly.io/abc123/video.mp4",
12      "title": "Your Media Title",
13      "duration": 300,
14      "creditsUsed": 53,
15      "fileSizeBytes": 52428800,
16      "filename": "video.mp4"
17    },
18    "startedAt": "2025-09-14T10:00:00Z",
19    "completedAt": "2025-09-14T10:01:00Z"
20  }
21}

Webhook Types

• import.completed - Import finished successfully
• import.failed - Import failed
• metadata.completed - Metadata extraction completed
• metadata.failed - Metadata extraction failed

Test Your Webhook

Use tools like ngrok for local testing:

bash
Copy
1# Terminal 1: Start your local server
2python -m http.server 8000
3
4# Terminal 2: Expose it publicly
5ngrok http 8000
6
7# Use the ngrok URL as your webhook URL
8# https://abc123.ngrok.io/webhook

8. Batch Operations

Process multiple URLs by making parallel requests:

bash
Copy
1#!/bin/bash
2
3API_KEY="your_api_key_here"
4WEBHOOK_URL="https://your-domain.com/webhook"
5
6# Array of URLs to import
7urls=(
8  "https://example.com/video1"
9  "https://example.com/video2"
10  "https://example.com/video3"
11)
12
13# Start all imports
14for url in "${urls[@]}"; do
15  echo "Starting import for: $url"
16
17  curl -X POST "https://api.importly.io/import" \
18       -H "Authorization: Bearer $API_KEY" \
19       -H "Content-Type: application/json" \
20       -d "{
21         \"url\": \"$url\",
22         \"videoQuality\": \"1080p\",
23         \"webhookUrl\": \"$WEBHOOK_URL\"
24       }" &
25done
26
27# Wait for all background jobs to complete
28wait
29
30echo "All imports started!"

9. Polling for Status Updates

If you prefer polling over webhooks, you can check status periodically:

bash
Copy
1#!/bin/bash
2
3API_KEY="your_api_key_here"
4IMPORT_ID="abc123"
5
6check_status() {
7  curl -s -X GET "https://api.importly.io/import/status?id=$IMPORT_ID" \
8       -H "Authorization: Bearer $API_KEY" \
9       | python -m json.tool
10}
11
12echo "Checking import status..."
13
14while true; do
15  response=$(check_status)
16  status=$(echo "$response" | python -c "import sys, json; print(json.load(sys.stdin)['data']['status'])")
17
18  echo "Current status: $status"
19
20  if [[ "$status" == "completed" ]] || [[ "$status" == "failed" ]]; then
21    echo "Final result:"
22    echo "$response"
23    break
24  fi
25
26  echo "Still processing... checking again in 5 seconds"
27  sleep 5
28done

10. Advanced Format Selection

Use format selectors for precise control over media quality:

bash
Copy
1# Get the best quality under 1GB
2curl -X POST "https://api.importly.io/import" \
3     -H "Authorization: Bearer YOUR_API_KEY" \
4     -H "Content-Type: application/json" \
5     -d '{
6       "url": "https://example.com/video",
7       "formatSelector": "best[filesize<1000M]"
8     }'
9
10# Get audio only in MP3 format
11curl -X POST "https://api.importly.io/import" \
12     -H "Authorization: Bearer YOUR_API_KEY" \
13     -H "Content-Type: application/json" \
14     -d '{
15       "url": "https://example.com/video",
16       "includeVideo": false,
17       "formatSelector": "bestaudio[ext=mp3]"
18     }'
19
20# Get specific resolution and codec
21curl -X POST "https://api.importly.io/import" \
22     -H "Authorization: Bearer YOUR_API_KEY" \
23     -H "Content-Type: application/json" \
24     -d '{
25       "url": "https://example.com/video",
26       "formatSelector": "best[height=720][vcodec^=avc1]"
27     }'

11. Rate Limiting & Best Practices

Respect rate limits and implement proper error handling:

bash
Copy
1#!/bin/bash
2
3make_request() {
4  local url=$1
5  local max_retries=3
6  local retry_count=0
7
8  while [ $retry_count -lt $max_retries ]; do
9    response=$(curl -w "%{http_code}" -s -X POST "https://api.importly.io/import" \
10                    -H "Authorization: Bearer $API_KEY" \
11                    -H "Content-Type: application/json" \
12                    -d "{\"url\": \"$url\"}")
13
14    http_code="${response: -3}"
15    body="${response%???}"
16
17    case $http_code in
18      200|201)
19        echo "Success: $body"
20        return 0
21        ;;
22      429)
23        echo "Rate limited, waiting 60 seconds..."
24        sleep 60
25        ;;
26      *)
27        echo "Error $http_code: $body"
28        ;;
29    esac
30
31    ((retry_count++))
32    echo "Retry $retry_count of $max_retries"
33    sleep $((retry_count * 2))  # Exponential backoff
34  done
35
36  echo "Failed after $max_retries attempts"
37  return 1
38}

12. Testing & Debugging

Useful commands for testing and debugging:

bash
Copy
1# Test with verbose output
2curl -v -X POST "https://api.importly.io/import" \
3     -H "Authorization: Bearer YOUR_API_KEY" \
4     -H "Content-Type: application/json" \
5     -d '{"url": "https://example.com/video"}'
6
7# Save response to file
8curl -X GET "https://api.importly.io/import/status?id=abc123" \
9     -H "Authorization: Bearer YOUR_API_KEY" \
10     -o response.json
11
12# Pretty print JSON response
13curl -s -X GET "https://api.importly.io/import/status?id=abc123" \
14     -H "Authorization: Bearer YOUR_API_KEY" \
15     | python -m json.tool
16
17# Check response time
18curl -w "@curl-format.txt" -s -X POST "https://api.importly.io/import" \
19     -H "Authorization: Bearer YOUR_API_KEY" \
20     -H "Content-Type: application/json" \
21     -d '{"url": "https://example.com/video"}'

Create curl-format.txt:

     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n

Why cURL?

cURL is perfect for:

• ✅ Quick testing - Test API endpoints instantly
• ✅ Debugging - Inspect requests and responses
• ✅ Automation - Create simple scripts and cron jobs
• ✅ Documentation - Easy to copy and share examples
• ✅ Language agnostic - Works with any tech stack

Next Steps

• Set up webhooks for real-time notifications
• Learn about format selectors for advanced control
• Check out SDK examples for your preferred language
• Review best practices for production usage

Complete Example

Check out our complete cURL examples on GitHub with advanced scripts and automation examples.