Developer Documentation

TokCaption API Documentation

A REST API to transcribe TikTok, Reels, and Shorts; run AI hook analysis and script rewrites; analyze competitors; and export transcripts at scale. Authenticate with an API key, submit a URL, and poll for the result. API access is available on the Pro plan.

REST API · v2.1.0

TokCaption API

Transcribe TikTok, Reels, and Shorts; run AI hook analysis; spy on competitors; and export at scale — all over a clean JSON REST API. Authenticate with an API key and start in two calls. Prefer AI assistants? The same tools are available as an MCP server for Claude and ChatGPT.

Base URL

https://tokcaption.com/api/v1

Auth

X-API-Key

Endpoints

31 across 7 groups

Authentication

Create an API key from Settings → API Keys (Pro plan). Send it on every request via the X-API-Key header. Dashboard and mobile clients can alternatively send a Supabase JWT as Authorization: Bearer <jwt>. Keep keys server-side — never ship them in a browser bundle.

curl "https://tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Quickstart

Submit a URL, then poll the job until it's done. A single URL often finishes inline — check the response status before polling.

Step 1 — Submit

POST /api/v1/jobs with your URLs. Store the returned job_id.

Step 2 — Poll

GET /api/v1/jobs/{jobId} every 1–2s until status is terminal, then read items[].transcript_text.

Just one URL and don't want to poll? Use GET /api/v1/quick for a synchronous result.

Errors & rate limits

Every error returns the same JSON envelope. Branch on code, not the HTTP status or message. On 429, honor the Retry-After header.

Error envelope

{
  "success": false,
  "error": "Free plan allows 5 transcripts per day.",
  "code": "QUOTA_EXCEEDED",
  "message": "Free plan allows 5 transcripts per day.",
  "error_info": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows 5 transcripts per day.",
    "details": {
      "limit_type": "daily",
      "daily_limit": 5,
      "retry_after_seconds": 43200
    }
  },
  "details": {
    "limit_type": "daily",
    "daily_limit": 5,
    "retry_after_seconds": 43200
  }
}

All error codes

Code	HTTP	Meaning
AUTH_REQUIRED	401	Missing or invalid credentials. Send a valid X-API-Key, or an Authorization: Bearer <jwt> header.
VALIDATION_ERROR	400	Invalid request body, query params, or path. The message and details explain what to fix.
PLAN_REQUIRED	403	This feature or option requires a Pro plan. Upgrade to unlock.
NOT_FOUND	404	Job, transcript, or resource not found or not owned by you.
QUOTA_EXCEEDED	429	Transcript, agent, download, or translation quota reached. Resets daily (free) or per billing cycle (Pro). See details.reset_at.
RATE_LIMIT_EXCEEDED	429	Too many submit, poll, or agent requests in a short window. Honor the Retry-After header / details.retry_after_seconds.
DUPLICATE_REQUEST	409	An idempotency_key was reused. The original request already ran.
TRANSLATION_LIMIT_EXCEEDED	429	Monthly translation quota reached. Resets on your billing cycle.
UPSTREAM_TEMPORARY_ERROR	503	TikTok temporarily blocked or rate-limited the request. Retry with backoff.
SEGMENTS_UNAVAILABLE	400	Timed segments are required for this export format (srt/vtt) but the transcript has none.
INTERNAL_ERROR	500	Unexpected server error. Retry, and contact support if it persists.

Transcription

Submit TikTok, Reels, or Shorts URLs for transcription and track job progress.

POST/api/v1/jobs

Submit transcription job

submit limit

Submit 1..N TikTok / Reels / Shorts URLs for transcription. Batch size is capped by your plan; a single URL may return a finished result inline.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

A single URL can return HTTP 200 with a terminal completed or failed payload when processing finishes inline.
Batches return HTTP 202 with job_id, an aggregate status, and per-item statuses inside items.
Inspect the items array for per-video status: queued, processing, completed, or failed.
Setting include_download_assets: true on the free plan returns PLAN_REQUIRED (403).

Body fields

`urls`required string[]	TikTok video URLs. Free plan batch limit is 5.
`output_language` string	Target transcript language (ISO code). Defaults to en.
`also_translate_to` string[]	Extra languages to translate the transcript into.
`allow_asr_fallback` boolean	Transcribe audio when no caption track exists. Defaults to false.
`include_download_assets` boolean	Persist video/cover assets for download. Pro only.
`idempotency_key` string	Dedupe key; reusing it returns the original job.

Success response · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Immediate single success

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Single failure (no captions)

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

List jobs

List your transcription jobs, newest first, with cursor pagination.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/jobs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

`cursor` string (ISO date) · query	Pass the previous next_cursor to page back in time.
`limit` integer · query	Page size, 1–50. Defaults to 20.
`status` string · query	Filter by job status (e.g. completed, processing, failed).

Success response

{
  "jobs": [
    {
      "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
      "created_at": "2026-06-23T10:02:11.000Z",
      "updated_at": "2026-06-23T10:02:48.000Z",
      "origin": "api",
      "status": "completed",
      "collection_name": null
    }
  ],
  "next_cursor": "2026-06-23T10:02:11.000Z"
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

Poll job status

poll limit

Poll a job until it reaches a terminal state. Returns aggregate counts plus full per-item detail.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Terminal job states are completed, partial, or failed; individual items inside a job may differ.
Completed items include transcript_text, segments, translations, metadata, and assets.
Poll at a sensible interval (every 1–2s). On HTTP 429, honor retry_after_seconds.

Parameters

jobIdrequired

string · path

Job ID returned by POST /api/v1/jobs.

Success response

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/jobs/{jobId}/cancel

Cancel a job

Cancel queued or processing items in a job. Released items return their quota.

Auth: API key or JWTReq: noneRes: application/json

curl -X POST "https://tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6/cancel" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

jobIdrequired

string · path

Job ID to cancel.

Success response

{
  "cancelled_count": 3
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Quick transcribe (one URL)

submit limit

Submit a single URL and wait (up to ~55s) for a terminal result — a synchronous shortcut over jobs.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/quick?url=https%3A%2F%2Fwww.tiktok.com%2F%40creator%2Fvideo%2F1234567890" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Returns HTTP 200 once terminal (completed/failed), or HTTP 202 if still processing when the wait window elapses — then poll /api/v1/jobs/{jobId}.

Parameters

urlrequired

string · query

A single TikTok video URL.

Success response

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed"
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Bulk import

Prosubmit limit

Submit a list of URLs or raw text containing links. Free plan accepts 1 URL; bulk requires Pro.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/import/collection" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en"}'

Body fields

`urls` string[]	Explicit URL list. Provide this or text.
`text` string	Free text; TikTok links are extracted automatically.
`output_language` string	Target transcript language. Defaults to en.
`allow_asr_fallback` boolean	Transcribe audio when no captions exist. Defaults to false.

Success response · HTTP 202

{
  "total_urls_found": 5,
  "valid_urls": 4,
  "jobs_created": 1,
  "job_ids": [
    "b86f89f2-34f6-4b76-88f6-03c13c51b7a6"
  ],
  "invalid_urls": [
    "https://example.com/not-a-video"
  ]
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Transcripts

Read, search, export, and download finished transcripts and their assets.

GET/api/v1/history

List / search transcripts

poll limit

Paginated, searchable transcript history with status, folder, and ordering filters.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/history?page=1" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

`page` integer · query	1-based page number. Defaults to 1.
`limit` integer · query	Page size, 1–100. Defaults to 15.
`search` string · query	Full-text match on transcript text and source URL.
`status` string · query	completed \| failed \| all. Defaults to all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Success response

{
  "transcripts": [
    {
      "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "tiktok_video_id": "1234567890",
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "created_at": "2026-06-23T10:02:11.000Z",
      "completed_at": "2026-06-23T10:02:48.000Z",
      "folder": null
    }
  ],
  "page": 1,
  "limit": 15,
  "has_more": true,
  "total_count": 42,
  "total_pages": 3
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Get a transcript

poll limit

Fetch a single transcript by ID with full text, segments, translations, metadata, and assets.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

idrequired

string · path

Transcript ID.

Success response

{
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed",
  "input_url": "https://www.tiktok.com/@creator/video/1234567890",
  "output_language": "en",
  "source_language": "en",
  "selected_track_type": "creator",
  "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  },
  "metadata": {
    "author_username": "foodnetwork",
    "duration_seconds": 29
  },
  "completed_at": "2026-06-23T10:02:48.000Z"
}

Errors

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

GET/api/v1/transcripts/{id}/export

Export a transcript

Download one transcript as txt, srt, vtt, csv, json, or pdf. json and pdf require Pro.

Auth: API key or JWTReq: noneRes: file download

curl -X GET "https://tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/export?format=srt" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Returns the file with Content-Disposition: attachment. format=json returns { id, text, segments, metadata }.
srt/vtt require timed segments — otherwise SEGMENTS_UNAVAILABLE.

Parameters

`id`required string · path	Transcript ID.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. Defaults to txt.
`language` string · query	Export a translation instead of the source language.

Success response

{
  "note": "Binary/text download. Example shows the format=json body.",
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "metadata": {
    "author_username": "foodnetwork"
  }
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Batch export (ZIP)

Export many transcripts at once as a ZIP, by ID list or by filters. json/pdf require Pro.

Auth: API key or JWTReq: application/jsonRes: application/zip

curl -X POST "https://tokcaption.com/api/v1/transcripts/export-batch" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"srt","filters":{"status":"completed","orderBy":"created_at_desc"}}'

Body fields

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. Defaults to txt.
`ids` string[]	Explicit transcript IDs. Omit to use filters.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Only completed transcripts are exported.

Success response

{
  "note": "Returns a ZIP attachment named tokcaption-srt-export-<date>.zip."
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Delete a transcript

Permanently delete a transcript, its stored assets, and folder links.

Auth: API key or JWTReq: noneRes: application/json

curl -X DELETE "https://tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

idrequired

string · path

Transcript ID.

Success response

{
  "deleted": true
}

Errors

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Transcript stats

poll limit

Aggregate counts for your account.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/transcripts/stats" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Success response

{
  "total": 944,
  "completed": 702,
  "failed": 212,
  "folders": 5
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}/download/video

Download source video

Pro

Download the original TikTok video as MP4. Pro only, and counts against your monthly download quota.

Auth: API key or JWTReq: noneRes: video/mp4

curl -X GET "https://tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/download/video" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Returns video/mp4 as an attachment. Quota is consumed only on a successful stream.

Parameters

idrequired

string · path

Transcript ID.

Success response

{
  "note": "Binary video/mp4 attachment."
}

Errors

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

AI Agents

Run hook analysis, script rewrites, and virality scoring on a transcript. (Pro)

POST/api/v1/agents/{agentType}

Run an AI agent

Proagent limit

Queue an AI analysis on a completed transcript. agentType is one of hooks, script_rewrite, virality_explain, hook_score.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/agents/hooks" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2","input":{}}'

Body fields

`transcript_id`required string	A completed transcript to analyze.
`input` object	Optional agent-specific parameters.

Parameters

agentTyperequired

string · path

hooks | script_rewrite | virality_explain | hook_score.

Success response · HTTP 202

{
  "run_id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "queued"
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

List agent runs

List your agent runs, newest first, with cursor pagination.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/agents/runs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

`cursor` string (ISO date) · query	Pass next_cursor to page back.
`limit` integer · query	Page size, 1–50. Defaults to 20.

Success response

{
  "runs": [
    {
      "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "status": "completed",
      "agent_type": "hooks",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "created_at": "2026-06-23T10:05:00.000Z"
    }
  ],
  "next_cursor": null
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/agents/runs/{runId}

Get an agent run

Fetch one agent run, including its structured output once complete.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/agents/runs/a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

runIdrequired

string · path

Agent run ID.

Success response

{
  "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "agent_type": "hooks",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "output": {
    "hooks": [
      "The first 3 seconds promise a payoff..."
    ]
  },
  "output_text": "The first 3 seconds promise a payoff...",
  "model": "claude-...",
  "completed_at": "2026-06-23T10:05:09.000Z"
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Competitor Spy

Queue and read competitor profile analyses across a creator's recent videos.

POST/api/v1/spy/analyze

Queue competitor analysis

Analyze a creator's recent videos. Returns an analysisId to poll for progress.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/spy/analyze" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"foodnetwork","limit":30}'

Body fields

`username`required string	TikTok username (with or without leading @).
`limit` integer	Videos to analyze: 10, 20, or 30. Defaults to 30.

Success response · HTTP 202

{
  "success": true,
  "analysisId": "c1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "queued",
  "queue": "default"
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/spy/analyses/{id}/status

Poll analysis status

Lightweight progress polling for a competitor analysis.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/spy/analyses/85f4dd35-3bc5-413f-81a6-63e0b61722d2/status" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

idrequired

string · path

analysisId from POST /spy/analyze.

Success response

{
  "id": "c1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "target_username": "foodnetwork",
  "status": "processing",
  "progress": {
    "stage": "analyzing",
    "percent": 60
  },
  "videos_analyzed": 18,
  "created_at": "2026-06-23T10:10:00.000Z"
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

GET/api/v1/spy/analyses/{id}

Get analysis result

Fetch the full payload of a completed competitor analysis.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/spy/analyses/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Parameters

idrequired

string · path

analysisId.

Success response

{
  "success": true,
  "analysisId": "c1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "target_username": "foodnetwork",
  "average_views": 220000,
  "top_hooks": [
    "POV:",
    "3 things nobody tells you..."
  ]
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

GET/api/v1/spy/history

List analyses

Your 30 most recent competitor analyses.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/spy/history" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Success response

{
  "runs": [
    {
      "id": "c1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "target_username": "foodnetwork",
      "status": "completed",
      "videos_analyzed": 30,
      "average_views": 220000,
      "created_at": "2026-06-23T10:10:00.000Z"
    }
  ]
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

Extract & Translate

Lower-level primitives: scrape metadata, translate text, and classify pasted input.

POST/api/v1/extract/metadata

Scrape metadata

Resolve a TikTok URL to its metadata and the best available subtitle track without creating a job.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/extract/metadata" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@creator/video/1234567890"}'

Body fields

`url`required string	A TikTok video URL.
`output_language` string	Preferred subtitle language. Defaults to en.

Success response

{
  "normalized_url": "https://www.tiktok.com/@creator/video/1234567890",
  "source_language": "en",
  "selected_track_type": "creator",
  "subtitle_format": "webvtt",
  "metadata": {
    "author_username": "creator",
    "duration_seconds": 29
  }
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Translate text

Translate transcript text and/or timed segments into one or more languages.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/extract/translate" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_text":"Whenever I'm asked to teach a beginner how to cook...","output_language":"es"}'

Body fields

`full_text` string	Text to translate. Provide this and/or segments.
`segments` TranscriptSegment[]	Timed segments to translate while preserving timing.
`output_language` string	Primary target language. Defaults to en.
`additional_languages` string[]	Extra target languages.

Success response

{
  "fullText": "Cada vez que me piden que enseñe a un principiante a cocinar...",
  "segments": [],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  }
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Resolve pasted input

Classify pasted text / @handles / URLs into video URLs, a collection preview, or a profile preview.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/workspace/resolve" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"@foodnetwork"}'

Body fields

`text` string	Raw pasted input. Provide this or urls.
`urls` string[]	Explicit URL list.

Success response

{
  "kind": "profile",
  "profile": {
    "username": "foodnetwork",
    "video_count": 1200
  }
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Folders

Organize transcripts into folders.

GET/api/v1/folders

List folders

List your folders with item counts.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Success response

{
  "folders": [
    {
      "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Cooking hooks",
      "created_at": "2026-06-23T10:00:00.000Z",
      "item_count": 12
    }
  ]
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Create a folder

Create a folder to group transcripts.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cooking hooks"}'

Body fields

namerequired

string

Folder name.

Success response · HTTP 201

{
  "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Cooking hooks",
  "created_at": "2026-06-23T10:00:00.000Z"
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

POST/api/v1/folders/{folderId}/items

Add transcript to folder

Add a transcript to a folder (idempotent).

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/folders/f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d/items" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2"}'

Body fields

transcript_idrequired

string

Transcript to add.

Parameters

folderIdrequired

string · path

Target folder ID.

Success response · HTTP 201

{
  "added": true
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Account, Keys & Billing

Manage API keys, inspect plans and quota, and submit feedback.

POST/api/v1/api-keys

Create an API key

Pro

Generate a live API key. The full key is shown once — store it securely. Pro only.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production server"}'

Body fields

namerequired

string

A label to identify the key.

Success response · HTTP 201

{
  "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Production server",
  "key_prefix": "tok_live_a1b2c3",
  "key": "tok_live_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5",
  "created_at": "2026-06-23T10:00:00.000Z",
  "warning": "Save this key now — it will not be shown again."
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

List API keys

Pro

List your active keys by prefix (the secret is never returned). Pro only.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Success response

{
  "keys": [
    {
      "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Production server",
      "key_prefix": "tok_live_a1b2c3",
      "last_used_at": "2026-06-23T10:30:00.000Z",
      "created_at": "2026-06-23T10:00:00.000Z",
      "revoked_at": null
    }
  ]
}

Errors

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

List plans

Public list of active plans and their limits. No auth required.

Auth: Public (no auth)Req: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/plans"

Success response

{
  "plans": [
    {
      "id": "free",
      "price_cents": 0,
      "billing_interval": "none",
      "free_daily_limit": 5,
      "agents_enabled": false,
      "downloads_enabled": false,
      "features": [
        "5 transcripts per day",
        "TXT & SRT export"
      ]
    },
    {
      "id": "pro_monthly",
      "price_cents": 900,
      "billing_interval": "month",
      "agents_enabled": true,
      "downloads_enabled": true,
      "features": [
        "Unlimited transcripts",
        "30 AI agent runs / month",
        "API access"
      ]
    }
  ]
}

Errors

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Subscription & quota

Your current plan, subscription status, and live usage/quota across transcripts, agents, downloads, and translations.

Auth: API key or JWTReq: noneRes: application/json

curl -X GET "https://tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Success response

{
  "plan": {
    "id": "free",
    "price_cents": 0,
    "billing_interval": "none"
  },
  "subscription_status": null,
  "quota": {
    "transcripts": {
      "window": "daily",
      "limit": 5,
      "used": 2,
      "remaining": 3,
      "is_unlimited": false,
      "reset_at": "2026-06-24T00:00:00.000Z"
    },
    "agents": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    }
  }
}

Errors

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Submit feedback

Send product feedback, a bug report, or a feature request.

Auth: API key or JWTReq: application/jsonRes: application/json

curl -X POST "https://tokcaption.com/api/v1/feedback" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"feature","rating":5,"message":"Add a Zapier integration please!"}'

Body fields

`category`required string	bug \| feature \| improvement \| other.
`message`required string	Up to 2000 characters.
`rating` integer \| null	Optional 1–5 rating.

Success response

{
  "success": true
}

Errors

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…