Skip to main content
The Content API manages your video library. Use it to create content records, update metadata, and control availability.

​
Endpoints

MethodEndpointDescription
POST/v1/contentCreate content from URL
GET/v1/contentList all content
GET/v1/content/{id}Get content by ID
PATCH/v1/content/{id}Update content
DELETE/v1/content/{id}Delete content

​
Create content

Creates a new content record and starts processing. 
POST /v1/content

​
Request body

​
sourceUrl
string
required
URL to the source video file. Must be publicly accessible or a signed URL.
​
title
string
required
Display title (max 200 characters).
​
description
string
Optional description (max 2000 characters).
​
tags
string[]
Tags for categorization and filtering.
​
metadata
object
Custom metadata key-value pairs.
​
visibility
string
default:"private"
Initial visibility: private, unlisted, or public.
​
publishAt
string
ISO 8601 timestamp for scheduled publishing.

​
Example request

curl -X POST https://api.shortkit.dev/v1/content \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://storage.example.com/videos/my-video.mp4",
    "title": "Product Launch Announcement",
    "description": "Exciting news about our latest product",
    "tags": ["announcement", "product"],
    "metadata": {
      "campaign": "spring-2024",
      "creator": "marketing-team"
    },
    "visibility": "private"
  }'

​
Response

{
  "data": {
    "id": "cnt_abc123",
    "title": "Product Launch Announcement",
    "description": "Exciting news about our latest product",
    "status": "processing",
    "visibility": "private",
    "duration": null,
    "aspectRatio": null,
    "tags": ["announcement", "product"],
    "metadata": {
      "campaign": "spring-2024",
      "creator": "marketing-team"
    },
    "thumbnails": null,
    "createdAt": "2024-02-04T12:00:00Z",
    "updatedAt": "2024-02-04T12:00:00Z",
    "publishedAt": null
  },
  "meta": {
    "requestId": "req_xyz789"
  }
}

​
List content

Retrieves a paginated list of content. 
GET /v1/content

​
Query parameters

​
limit
integer
default:20
Items per page (1-100).
​
cursor
string
Pagination cursor from previous response.
​
status
string
Filter by status: processing, ready, failed.
​
visibility
string
Filter by visibility: private, unlisted, public.
​
tags
string
Comma-separated tags to filter by.
​
createdAfter
string
Filter by creation date (ISO 8601).
​
createdBefore
string
Filter by creation date (ISO 8601).
​
search
string
Search titles and descriptions.

​
Example request

curl "https://api.shortkit.dev/v1/content?limit=20&status=ready&tags=product" \
  -H "Authorization: Bearer sk_live_your_secret_key"

​
Response

{
  "data": [
    {
      "id": "cnt_abc123",
      "title": "Product Launch Announcement",
      "status": "ready",
      "visibility": "public",
      "duration": 45.2,
      "aspectRatio": "9:16",
      "thumbnails": {
        "default": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/default.jpg",
        "small": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/small.jpg"
      },
      "createdAt": "2024-02-04T12:00:00Z",
      "publishedAt": "2024-02-04T14:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "nextCursor": "eyJvZmZzZXQiOjIwfQ=="
  }
}

​
Get content

Retrieves a single content item by ID. 
GET /v1/content/{id}

​
Path parameters

​
id
string
required
Content ID (e.g., cnt_abc123).

​
Example request

curl https://api.shortkit.dev/v1/content/cnt_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key"

​
Response

{
  "data": {
    "id": "cnt_abc123",
    "title": "Product Launch Announcement",
    "description": "Exciting news about our latest product",
    "status": "ready",
    "visibility": "public",
    "duration": 45.2,
    "aspectRatio": "9:16",
    "resolution": {
      "width": 1080,
      "height": 1920
    },
    "codecs": ["h264", "av1"],
    "tags": ["announcement", "product"],
    "metadata": {
      "campaign": "spring-2024",
      "creator": "marketing-team"
    },
    "thumbnails": {
      "default": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/default.jpg",
      "small": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/small.jpg",
      "animated": "https://cdn.shortkit.dev/thumbnails/cnt_abc123/preview.webp"
    },
    "streamingUrls": {
      "hls": "https://video.shortkit.dev/v1/streams/cnt_abc123/manifest.m3u8",
      "dash": "https://video.shortkit.dev/v1/streams/cnt_abc123/manifest.mpd"
    },
    "analytics": {
      "impressions": 12500,
      "plays": 8200,
      "completions": 4100,
      "averageWatchTime": 32.5
    },
    "createdAt": "2024-02-04T12:00:00Z",
    "updatedAt": "2024-02-04T14:30:00Z",
    "publishedAt": "2024-02-04T14:00:00Z"
  },
  "meta": {
    "requestId": "req_xyz789"
  }
}

​
Content status

StatusDescription
processingVideo is being transcoded
readyVideo is ready for playback
failedProcessing failed

​
Update content

Updates content metadata. Cannot update source video after creation. 
PATCH /v1/content/{id}

​
Request body

​
title
string
Updated title.
​
description
string
Updated description.
​
tags
string[]
Replace all tags.
​
metadata
object
Merge with existing metadata (use null to remove keys).
​
visibility
string
Update visibility: private, unlisted, public.
​
publishAt
string
Schedule publishing (ISO 8601) or null to cancel.

​
Example request

curl -X PATCH https://api.shortkit.dev/v1/content/cnt_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "visibility": "public",
    "tags": ["featured", "product"],
    "metadata": {
      "featured": true,
      "campaign": null
    }
  }'

​
Response

Returns the updated content object.

​
Delete content

Permanently deletes content and all associated data. 
DELETE /v1/content/{id}

​
Path parameters

​
id
string
required
Content ID to delete.

​
Example request

curl -X DELETE https://api.shortkit.dev/v1/content/cnt_abc123 \
  -H "Authorization: Bearer sk_live_your_secret_key"

​
Response

{
  "data": {
    "id": "cnt_abc123",
    "deleted": true
  },
  "meta": {
    "requestId": "req_xyz789"
  }
}
Deletion is permanent. All video files, thumbnails, and analytics data are removed within 24 hours.

​
Content object

​
id
string
Unique identifier (prefix: cnt_).
​
title
string
Display title.
​
description
string
Optional description.
​
status
string
Processing status: processing, ready, failed.
​
visibility
string
Visibility: private, unlisted, public.
​
duration
number
Video duration in seconds (available when ready).
​
aspectRatio
string
Aspect ratio (e.g., 9:16, 16:9).
​
resolution
object
Source resolution with width and height.
​
codecs
string[]
Available codecs (e.g., ["h264", "av1"]).
​
tags
string[]
Content tags.
​
metadata
object
Custom metadata.
​
thumbnails
object
Thumbnail URLs by size.
​
streamingUrls
object
HLS and DASH streaming URLs (signed, time-limited).
​
analytics
object
Engagement metrics summary.
​
createdAt
string
Creation timestamp (ISO 8601).
​
updatedAt
string
Last update timestamp (ISO 8601).
​
publishedAt
string
Publication timestamp (ISO 8601).

​
Webhooks

Subscribe to content lifecycle events:
EventTrigger
content.readyProcessing completed
content.erroredProcessing failed
See Webhooks for setup instructions.

​
Next steps

Uploads

Direct file upload endpoint.

Bulk operations

Batch content operations.