Import Endpoint

The import endpoint provides two operations:

• POST https://api.importly.com/import - Start a new import
• GET https://api.importly.com/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.

Overview

Use /import when you need to:

• Store media temporarily so you can process or retrieve it later.
• Offload the complexity of downloads, retries, and proxies.

Parameters

See also: Format selectors for common presets and examples.

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

Example Request (selector)

curl -X POST "https://api.importly.io/import" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/video.mp4",
       "format": "bestvideo[height<=1080][vcodec^=avc1]+bestaudio[ext=m4a]/best[height<=1080][ext=mp4]",
       "webhook_url": "https://your-app.com/api/importly-webhook"
     }'

Example Request (numeric shorthand)

curl -X POST "https://api.importly.io/import" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/video.mp4",
       "format": "720p",
       "webhook_url": "https://your-app.com/api/importly-webhook"
     }'

JavaScript Example

const response = await fetch("https://api.importly.io/import", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/video.mp4",
    // Either a selector string ...
    // format: "bestvideo[height<=720][vcodec^=avc1]+bestaudio[ext=m4a]/best[height<=720][ext=mp4]",
    // ...or a format shorthand with audio
    format: "720p",
    webhook_url: "https://your-app.com/api/importly-webhook",
  }),
});

const result = await response.json();
console.log(result);

Example Response

{
  "success": true,
  "data": {
    "importId": "abc123",
    "status": "importing",
    "message": "Media import has started. You will receive a webhook when it's complete."
  }
}

• 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:

GET https://api.importly.com/import/status?id={importId}

Example Status Check

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

Status Response

{
  "success": true,
  "data": {
    "importId": "abc123",
    "status": "completed",
    "mediaUrl": "https://cdn-storage.importly.io/abc123/video.mp4",
    "title": "Sample Video",
    "duration": 314,
    "creditsUsed": 78,
    "message": "Import completed successfully"
  }
}

• importId: The unique import identifier
• status: Current status (queued, importing, failed, completed)
• mediaUrl: URL to download the media file (available when status is completed)
• creditsUsed: Final usage cost
• message: A short summary or error description

Data Retention & Retrieval

• 7-Day Retention: Your media stays on Importly's servers for up to 7 days.
• Manual Download: You can retrieve the file from the final mediaUrl once the job is complete (via webhooks or the status endpoint).

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.
• 500 Internal Server Error: Check status page or retry after some delay.

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.