API documentation

Your first export

Create an account, copy an API key with live:write and jobs:read, then follow these three steps. New accounts receive 10 credits once; the export uses credits.

BASE_URL="<your preview origin>"
# Set SHORTDRAMAKIT_API_KEY securely in your environment.

curl --fail -X POST "$BASE_URL/api/v1/live/jobs" \
  -H "Authorization: Bearer $SHORTDRAMAKIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: replace-with-a-unique-request-key' \
  -d '{
  "inputs": [
    "https://netshort.com/episode/the-mafia-bosses-max-level-nanny-2108386528632586241-ep-2"
  ],
  "format": "csv",
  "fields": [
    "platform",
    "platformId",
    "title",
    "metadataLocale",
    "reportedEpisodeCount",
    "sourceUrl",
    "observedAt"
  ]
}'

BASE_URL="<your preview origin>"
# Set SHORTDRAMAKIT_API_KEY securely in your environment.
JOB_ID="replace-with-data.id"

curl --fail -X POST "$BASE_URL/api/v1/live/jobs/$JOB_ID/advance" \
  -H "Authorization: Bearer $SHORTDRAMAKIT_API_KEY"

BASE_URL="<your preview origin>"
# Set SHORTDRAMAKIT_API_KEY securely in your environment.
DOWNLOAD_PATH="replace-with-data.downloadPath"

curl --fail --remote-name --remote-header-name \
  -H "Authorization: Bearer $SHORTDRAMAKIT_API_KEY" \
  "$BASE_URL$DOWNLOAD_PATH"

After this page loads, the examples use this preview’s origin. For another environment, set BASE_URL to its actual address. This example fetches current title data. Advance requests can require several passes; they reuse the same task and reservation.

This one-title example reserves up to 0.7 credits. Advancing the same task and downloading its saved result do not add another task charge. View pricing.

Authentication and scopes

Create a key in the dashboard, copy its secret once and keep it in server-side secret storage. Send a bearer key only to endpoints that accept its scope.

BASE_URL="<your preview origin>"
# Set SHORTDRAMAKIT_API_KEY securely in your environment.

curl "$BASE_URL/api/v1/live/jobs" \
  -H "Authorization: Bearer $SHORTDRAMAKIT_API_KEY"

jobs:read

Read owned tasks, files and manifests. Does not run tools or start acquisition.

jobs:write

Prepare episode tables from completed metadata exports; this scope does not grant source acquisition or media writes.

live:write

Create and control current metadata, candidate-discovery and platform-download tasks. Source execution still requires an enabled runtime and its configured allowance.

media:write

Delete owned delivered video files. It does not grant source acquisition.

Key limits

Up to 5 active keys. Each key permits 600 requests per UTC minute, with no daily request cap. Usage is recorded even if an admitted operation later fails.

Use both the relevant write scope and jobs:read for a script that creates a task and downloads its result. A key’s permissions apply only to its owner’s resources.

Public capability and pricing reads do not authenticate API keys. Omit Authorization; if supplied, it is ignored and does not consume the key’s request allowance. Account settings, key management and billing require browser sign-in. Session mutations must be same-origin. Do not combine a session cookie with a bearer key.

Choose an operation

Open the outcome you need for its routes, input contract and access rules. Each listed key scope is an alternative to a signed-in owner session unless the route is marked public.

Follow a task to its result

Drama-list collection and episode-download workflows retain private tasks that you can return to. A task ID is an owned resource, not a public share link.

1. Create once. Save the returned task ID. Task-creation endpoints for current exports, discovery and platform downloads require Idempotency-Key.
2. Read status. Use the task’s GET route. A read does not initiate source acquisition. Inspect per-input outcomes and available action flags before continuing.
3. Advance the supported workflow. Current exports, candidate batches and platform downloads expose advance.
4. Download the returned output. Use the exact downloadPath or media file ID, and retain revision and expiry information. Partial results may include a usable file with missing items recorded.

Cancellation, recovery and expiry

Cancellation stops future processing; it cannot undo a source request already accepted. Cancelled paid exports are final: canResume is false and resume returns 409 billing_task_finished. Existing completed records remain downloadable. Start a new task with a new Idempotency-Key to run again.

Current exports can report needs_attention; use their message and canAdvance flag to decide whether to retry. Source tasks expose their own actions. Follow each resource’s expiresAt, sourceExpiresAt or file expiry rather than treating task retention as permanent storage.

Handle errors and retries

Read the HTTP status together with error.code, error.message and error.requestId. Preserve the request ID when reporting a failure.

After a connection failure, read a known task before sending another action. Retry idempotent creation with its original key and payload. Keys of 8–128 letters, digits, underscores or hyphens work across the task-creation endpoints.

Fields and responses

Metadata exports share these selectable fields. IDs remain strings, missing values remain unknown, and language editions remain separate records.

JSON preserves ID strings exactly. CSV prefixes numeric IDs with an apostrophe to prevent spreadsheet rounding.

Input outcomes and task status

Each current export reports successful, duplicate, unsupported, pending and failed inputs. Inspect each input and the task’s progress/action flags. A partial result remains downloadable when resultCount is positive; incomplete inputs do not become fabricated rows.

Response envelopes and files

Media management JSON uses { "data": { "job": ... }, "requestId": "..." }, with jobs, files, artifact or deleted as appropriate. For example, deletion returns { "data": { "deleted": true }, "requestId": "..." }. Platform downloads use { download, requestId } or { downloads, requestId }. Manifests have their own document shape. CSV, JSON and ZIP downloads are attachment responses, not JSON envelopes.

Availability and preview limits

Availability belongs to the environment you call. A documented endpoint or a granted scope does not enable its source or processing runtime.

Drama-list inputs

Current exports accept up to 20 supported title links. Discovery returns bounded candidates; metadata enrichment is a separate priced step.

Capability values

local means processing already acquired source data; live means source execution is enabled; unavailable means that operation is disabled in this environment. API processing marked local runs on the service.

Source coverage

Current metadata supports bounded title reads. Keyword/category discovery and episode delivery have narrower platform coverage in the operation reference. None implies an exhaustive catalog or complete playable series.

Access and cost

Every successful new run costs at least 0.1 credit, rounded up once per task. New accounts receive 10 credits once. Website and API share one prepaid balance. Status checks and existing-result downloads add no charge; unavailable rates cannot start a task.

Release status

This reference includes local implementation. The public preview may expose fewer capabilities. Production availability at api.shortdramakit.com has not been announced.