Skip to main content
POST
Import up to 100 content items in a single request. Provide source URLs (cloud storage, CDN, public URLs) and ShortKit downloads, processes, and creates the content. Use this when you have media hosted elsewhere — migrating from another platform, importing from a CMS, or pulling from cloud storage.

​
Request body

​
string
A webhook URL that ShortKit will POST to as each item progresses through the import pipeline. See Callback lifecycle for the payload shape and delivery behavior.
​
object[]
required
Array of content items to import. Min 1, max 100 per request.Each item accepts the same metadata fields as Upload (title, description, tags, section, author, customMetadata, publishAt, expiresAt, generateSubtitles, autoScrollInterval), plus:
  • protected (boolean) — When true, playback is gated behind a short-lived signed streaming URL. When omitted, defaults to your organization’s default. See Protected Content.
For videos:
  • sourceUrl (string, required) — URL to the video file.
  • externalId (string) — Your own identifier for this content. Used for idempotency — if you re-import an item with the same externalId, ShortKit skips it instead of creating a duplicate.
  • priority (string) — "high" or "normal". Defaults to "normal". A "high" item is processed ahead of every "normal" import. See Processing priority.
For image carousels:
  • images (object[], required) — Array of image objects, each with:
    • sourceUrl (string, required) — URL to the image file.
    • altText (string) — Accessibility text.
    • position (integer) — Display order (0-indexed).
  • externalId (string) — Same idempotency behavior as videos.
For video carousels: Video carousels cannot be created via the import endpoint — they reference existing video content items. Use Upload to create the carousel, then add videos via POST /v1/content/{id}/videos.

​
Processing behavior

  • Videos are queued for async processing. They return with status: "queued" and transition to processing once transcoding begins, then ready once it completes. This typically takes 30–120 seconds depending on file size.
  • Carousels are processed synchronously. Images are fetched and stored immediately — carousels in the response are already ready.
If an individual item fails (bad URL, timeout, invalid format), it’s marked with an error message in the response. Other items in the batch are not affected.

​
Processing priority

Imports are generally processed in the order they arrive. Set priority: "high" on an item that shouldn’t wait its turn (ex. a time sensitive, user facing import, rather than a catalog backfill) and it jumps ahead of every item at the default priority still queued, including ones submitted earlier.
Every video item in the response reports its priority:
Priority applies to this endpoint only — the TikTok and Instagram import endpoints do not take a priority, and their items are processed at normal priority.

​
Callback lifecycle

When you provide a callbackUrl, ShortKit sends a POST request to that URL at each stage of the import pipeline. Your endpoint must respond with a 2xx status code to acknowledge receipt.

​
Callback events

ShortKit delivers up to three callbacks per video item as it moves through the pipeline: 1. content.imported with status: "processing" Sent when the video has been accepted for transcoding. This is where you receive the playbackId — store it in your backend alongside the content record.
The customMetadata field echoes the content’s custom metadata. For platform imports it carries the auto-extracted fields — for TikTok that’s tiktok_id, tiktok_url, tiktok_likes, tiktok_views, tiktok_comments, tiktok_author_name, tiktok_upload_date, and tiktok_timestamp (see Auto-populated metadata). It is {} when the content has no custom metadata. At this point the video is streamable (progressive delivery) but transcoding is not yet complete. If you plan to serve this content immediately, be aware that viewers of longer videos may experience buffering until encoding finishes. 2. content.imported with status: "ready" Sent when transcoding completes and the video is fully available at all quality levels. The payload shape is identical to the processing callback, with status set to "ready". 3. content.import_failed with status: "error" Sent if transcoding fails. The payload includes an error field describing the failure. No playbackId is included.

​
Retry behavior

Each callback is attempted up to 3 times. If your endpoint returns a non-2xx status code or is unreachable, ShortKit retries after 1 second, then again after 5 seconds. If all three attempts fail, the callback is abandoned. Callbacks are fire-and-forget — a failed callback does not affect the import itself. The video continues processing regardless.

​
Handling callback failures

If your webhook endpoint was down and you missed a callback, you can always retrieve the current status and playback ID by polling the content endpoint:
The callback includes the playbackId once the video has been accepted for processing. The SDK uses this playback ID to resolve streaming and thumbnail URLs.
Callbacks are only sent for video imports. Carousels are processed synchronously and are already ready in the initial import response.

​
Idempotency

Set externalId on each item to prevent duplicate imports. If you submit an item with an externalId that already exists in your organization, ShortKit skips it and returns the existing content record. This makes it safe to retry failed import requests without worrying about creating duplicates. Use whatever stable identifier you already have for each content record in your own system — a database primary key, a CMS slug, an internal content ID. As long as you use the same externalId for the same piece of content, ShortKit will recognize it as a duplicate and skip re-importing it. externalId is scoped to your organization, so different organizations can use the same values independently. The returned record keeps the values it was created with, including its priority — resubmitting an existing externalId at a higher priority returns the original item unchanged rather than raising it.

​
TikTok import

ShortKit imports content directly from TikTok via POST /v1/content/import/tiktok. It extracts metadata from the source automatically — you don’t provide title, description, or author. Each URL you submit is either a single video or a creator profile (for example https://www.tiktok.com/@username). A profile URL is expanded automatically into that creator’s most recent videos.

​
Request body

​
string[]
TikTok URLs to import. Min 1, max 20 per request. Each entry is either a single video URL or a creator profile URL. Submit at most one profile URL per request — pair it with single video URLs if you need to, and send additional profiles as separate requests. Provide exactly one of urls or items.
​
object[]
Alternative to urls that lets you attach your own metadata per URL. Min 1, max 20 per request; the same URL rules as urls apply. Provide exactly one of urls or items. Each item:
  • url (string, required) — a single video URL or a creator profile URL.
  • customMetadata (object) — string key/value pairs stamped onto the imported content at creation, stored alongside the auto-populated tiktok_* fields. A profile URL’s customMetadata is applied to every video expanded from that profile. The auto-populated tiktok_* keys are reserved — the importer’s values win on collision. If a URL is skipped as a duplicate, its metadata is skipped with it.
  • externalId (string) — Your own identifier for this content, used for idempotency exactly like the Import endpoint — re-importing with the same externalId returns the existing content instead of creating a duplicate. When omitted, ShortKit derives one from the platform (tiktok_<id> / instagram_<id>), which is what deduplicates repeat imports of the same video by default. Ignored on profile URLs (one id can’t apply across an expansion).
The Instagram endpoint accepts the same items shape.
​
integer
default:"20"
Maximum number of recent videos to import from each profile URL. Defaults to 20, up to 10000. Ignored for single video URLs.
​
integer
Import a profile’s most-viewed videos instead of its latest. When set to N (≥1), ShortKit scans a window of the profile’s recent videos and imports only the N with the highest view count — maxVideosPerProfile is ignored in this mode. When omitted, the latest maxVideosPerProfile videos are imported (default behavior).Only the selected videos are downloaded and processed — the rest of the scanned window is ranked on metadata alone and never ingested. Applies to profile URLs only.
​
string
A webhook URL that ShortKit POSTs to as each imported item progresses. Uses the same per-item payload and delivery behavior as the callback lifecycle above, plus a job-level callback when the import completes (see Tracking progress).

​
Response

TikTok imports are asynchronous. The endpoint returns a job summary, not the content records. A profile URL is expanded in the background, so the number of videos it produces is not known when the request returns — videosQueued reflects only single video URLs you submitted directly.
201

​
Tracking progress

A profile import can produce many content items over time, and there is no per-job status endpoint. Track progress two ways:
  • callbackUrl — receive a per-item content.imported callback as each video finishes processing (see Callback lifecycle), then a single job-level callback when the whole import completes:
  • GET /v1/content/import/status — poll for your organization’s import queue and daily usage. queued counts imports still waiting, broken out by priority: queuedInteractive counts items you sent with priority: "high", queuedExpress counts imports your team started from the ShortKit dashboard, and queuedBulk counts everything else. processing, readyToday, failedToday and dailyUsed count all content, including direct uploads.

​
Auto-populated metadata

ShortKit extracts and fills in the following fields automatically. You can change them after import using the Update Content endpoint.