Import Endpoint

The import endpoint provides two operations:

• POST https://api.importly.io/import - Start a new import
• GET https://api.importly.io/import/status?id={id} - Check import status

Purpose

Download media from a given URL onto Importly's servers and keep it available for up to 7 days. Optionally, upload directly to your own S3-compatible storage.

Parameters

See also: Format Options for detailed explanations and examples, and S3 Storage Integration for storing media in your own S3 bucket.

Authentication is required via the Authorization: Bearer <API_KEY> header.

Example Request (Default Quality)

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/video.mp4",
6       "webhookUrl": "https://your-app.com/api/importly-webhook"
7     }'

Example Request (High Quality)

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/video.mp4",
6       "videoQuality": "1080p",
7       "audioQuality": "best",
8       "webhookUrl": "https://your-app.com/api/importly-webhook"
9     }'

Example Request (Audio Only)

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/video.mp4",
6       "includeVideo": false,
7       "includeAudio": true,
8       "audioQuality": "high",
9       "webhookUrl": "https://your-app.com/api/importly-webhook"
10     }'

Example Request (With S3 Storage)

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/video.mp4",
6       "videoQuality": "1080p",
7       "store": true,
8       "storagePath": "videos/2024",
9       "storageFilename": "my-video",
10       "storageReturnLocation": true,
11       "webhookUrl": "https://your-app.com/api/importly-webhook"
12     }'

Learn more about S3 storage options in the S3 Storage Integration guide.

JavaScript Example

javascript
Copy
1const response = await fetch("https://api.importly.io/import", {
2  method: "POST",
3  headers: {
4    Authorization: "Bearer YOUR_API_KEY",
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    url: "https://example.com/video.mp4",
9    // Format options:
10    videoQuality: "1080p", // or "720p", "480p", "best", etc.
11    audioQuality: "high", // or "medium", "low", "best", etc.
12    includeVideo: true, // include video (default: true)
13    includeAudio: true, // include audio (default: true)
14    webhookUrl: "https://your-app.com/api/importly-webhook", // optional
15  }),
16});
17
18const result = await response.json();
19console.log(result);

Example 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}

• id: Unique identifier to track the import job.
• status: Could be queued, importing, failed, or completed.

Status Checking

To check the status of an import, make a GET request to:

bash
Copy
1GET https://api.importly.io/import/status?id={jobId}

Example Status Check

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

Status Response (Queued/Running)

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "queued",
6    "startedAt": null,
7    "completedAt": null
8  }
9}

When the job starts processing, the status changes to running and startedAt is populated:

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "running",
6    "startedAt": "2025-01-15T10:30:00.000Z",
7    "completedAt": null
8  }
9}

Status Response (Completed)

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "completed",
6    "result": {
7      "mediaUrl": "https://cdn-storage.importly.io/abc123/video.mp4",
8      "title": "Sample Video",
9      "duration": 314,
10      "creditsUsed": 78,
11      "message": "Import completed successfully"
12    },
13    "startedAt": "2025-01-15T10:30:00.000Z",
14    "completedAt": "2025-01-15T10:35:23.000Z"
15  }
16}

Status Response (Completed with S3 Storage)

When S3 storage is enabled (store: true), the response includes S3 information:

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "completed",
6    "result": {
7      "mediaUrl": "https://your-bucket.s3.us-east-1.amazonaws.com/videos/2024/my-video.mp4",
8      "title": "Sample Video",
9      "duration": 314,
10      "creditsUsed": 78,
11      "s3Storage": {
12        "url": "https://your-bucket.s3.us-east-1.amazonaws.com/videos/2024/my-video.mp4",
13        "bucket": "your-bucket",
14        "key": "videos/2024/my-video.mp4"
15      },
16      "message": "Import completed successfully and uploaded to S3"
17    },
18    "startedAt": "2025-01-15T10:30:00.000Z",
19    "completedAt": "2025-01-15T10:35:23.000Z"
20  }
21}

Status Response (Failed)

json
Copy
1{
2  "success": true,
3  "data": {
4    "jobId": "abc123",
5    "status": "failed",
6    "message": "Failed to download media from URL",
7    "startedAt": "2025-01-15T10:30:00.000Z",
8    "completedAt": "2025-01-15T10:31:15.000Z"
9  }
10}

Response Fields

• jobId: The unique import identifier
• status: Current status (queued, running, failed, completed)
• result: Object containing import results (only present when status is completed)
  • mediaUrl: URL to download the media file
  • title: Media title
  • duration: Duration in seconds
  • creditsUsed: Final usage cost
  • message: Success message
• message: Error description (only present when status is failed)
• startedAt: ISO timestamp when job processing started (null if not started)
• completedAt: ISO timestamp when job finished (null if not finished)

Data Retention & Retrieval

• 7-Day Retention: Your media stays on Importly's servers for up to 7 days.
• S3 Storage: Store media in your own S3 bucket for long-term retention. See S3 Storage Integration.
• Manual Download: You can retrieve the file from the final mediaUrl once the job is complete (via webhooks or the status endpoint).

Rate Limits

The import endpoint has specific rate limits to ensure fair usage:

• Request Rate: 240 requests per hour
• Concurrency: Maximum 2 concurrent import jobs
• Status Polling: 3,600 requests per hour for status checks

All responses include rate limit headers:

• X-RateLimit-Limit: Total requests allowed (240)
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when limit resets
• X-RateLimit-Window: Time window ("1 h")

Error Handling

• 400 Bad Request: Missing url, invalid JSON, or unreachable URL.
• 402 InsufficientCredits: You lack the credits to proceed with this import.
• 429 Too Many Requests: Rate limit or concurrency limit reached. Check retryAfter field and rate limit headers.
• 500 Internal Server Error: Check status page or retry after some delay.

429 Rate Limit Response Example

json
Copy
1{
2  "success": false,
3  "error": "Rate limit exceeded. Limit: 240 requests per 1 h",
4  "limit": 240,
5  "remaining": 0,
6  "reset": 1709901234000,
7  "retryAfter": 3600,
8  "endpoint": "/import"
9}

Best Practices

• Check Metadata First: Call /metadata to confirm file size and avoid large unexpected downloads.
• Webhook Configuration: Set up webhooks to automate tasks after the import finishes.
• Quality Selection: Use appropriate quality levels for your use case to balance file size and bandwidth.
• S3 Storage: Configure S3 storage for long-term retention and integration with your infrastructure. See S3 Storage Integration.
• Monitor Rate Limits: Check response headers to track usage and avoid hitting limits.
• Respect Concurrency: Wait for jobs to complete before starting new ones (max 2 concurrent).
• Implement Backoff: Use exponential backoff when receiving 429 responses.