API reference

The tscaps automation API is organized around RESTful JSON endpoints. Send your secret API key as a bearer token in the Authorization header with every request:

Authorization: Bearer TSCAPS_API_KEY
Content-Type: application/json

Base URL:

https://api.tscaps.io

Endpoints

Create a job

POST /v1/automation-jobs

Queues a new video processing job with caption styling and subtitle burn-in.

Request parameters

Request example

{
  "videoUrl": "https://example.com/reel.mp4",
  "templateId": "mira",
  "format": "mp4",
  "quality": "high",
  "resolution": { "width": 1080, "height": 1920 },
  "language": "en",
  "webhookUrl": "https://api.yourdomain.com/webhooks/tscaps"
}

Code example

curl -X POST https://api.tscaps.io/v1/automation-jobs \
  -H "Authorization: Bearer $TSCAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/reel.mp4",
    "templateId": "mira",
    "quality": "high"
  }'

const response = await fetch("https://api.tscaps.io/v1/automation-jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TSCAPS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    videoUrl: "https://example.com/reel.mp4",
    templateId: "mira",
    quality: "high",
  }),
});

const job = await response.json();

import os
import requests

response = requests.post(
    "https://api.tscaps.io/v1/automation-jobs",
    headers={"Authorization": f"Bearer {os.environ['TSCAPS_API_KEY']}"},
    json={
        "videoUrl": "https://example.com/reel.mp4",
        "templateId": "mira",
        "quality": "high",
    },
)

job = response.json()

Response

Returns 202 Accepted with the initial job record.

{
  "id": "9f2c48e1-5b7a-4a29-8874-9dfc8227b610",
  "status": "queued",
  "phase": "queued",
  "templateId": "mira",
  "quotedSeconds": null,
  "format": "mp4",
  "quality": "high",
  "resolution": null,
  "percent": null,
  "downloadUrl": null,
  "outputExpiresAt": null,
  "failureReason": null,
  "failureCode": null,
  "settledAt": null,
  "createdAt": "2026-09-12T10:11:38.000Z"
}

Get job status

GET /v1/automation-jobs/:id

Retrieves the current status and rendering progress of a specific job.

Path parameters

Code example

curl https://api.tscaps.io/v1/automation-jobs/9f2c48e1-5b7a-4a29-8874-9dfc8227b610 \
  -H "Authorization: Bearer $TSCAPS_API_KEY"

const response = await fetch("https://api.tscaps.io/v1/automation-jobs/9f2c48e1-5b7a-4a29-8874-9dfc8227b610", {
  headers: { Authorization: `Bearer ${process.env.TSCAPS_API_KEY}` },
});

const job = await response.json();

import os
import requests

response = requests.get(
    "https://api.tscaps.io/v1/automation-jobs/9f2c48e1-5b7a-4a29-8874-9dfc8227b610",
    headers={"Authorization": f"Bearer {os.environ['TSCAPS_API_KEY']}"},
)

job = response.json()

Response

Returns 200 OK with the complete job record.

{
  "id": "9f2c48e1-5b7a-4a29-8874-9dfc8227b610",
  "status": "succeeded",
  "phase": "succeeded",
  "templateId": "mira",
  "quotedSeconds": 74,
  "format": "mp4",
  "quality": "high",
  "resolution": { "width": 1080, "height": 1920 },
  "percent": null,
  "downloadUrl": "https://storage.tscaps.io/outputs/9f2c48e1-...?token=...",
  "outputExpiresAt": "2026-09-19T10:14:00.000Z",
  "failureReason": null,
  "failureCode": null,
  "settledAt": "2026-09-12T10:12:52.000Z",
  "createdAt": "2026-09-12T10:11:38.000Z"
}

Job lifecycle properties

• status: High-level execution state. One of:
  • queued: Waiting in queue for processing capacity.
  • running: Actively processing.
  • succeeded: Video rendered and available for download.
  • failed: Job encountered an unrecoverable error.
  • cancelled: Job was cancelled by user request.
• phase: Detailed operation currently in progress: queued, ingesting, transcribing, rendering, succeeded, failed, or cancelled.
• percent: Integer between 0 and 100 indicating rendering progress during the rendering phase. null in other phases.
• quotedSeconds: Measured duration of the input video in seconds (populated after ingest).
• downloadUrl: Presigned HTTPS download link to the final video (populated upon succeeded).
• outputExpiresAt: ISO timestamp when downloadUrl expires (rendered files remain available for 7 days).

Cancel a job

POST /v1/automation-jobs/:id/cancel

Cancels a queued or currently executing job. If the job is active, rendering stops immediately. All minutes reserved for the job are refunded back to your account balance.

This endpoint is idempotent: repeating the cancel call on an already cancelled job returns 200 OK.

Path parameters

Code example

curl -X POST https://api.tscaps.io/v1/automation-jobs/9f2c48e1-5b7a-4a29-8874-9dfc8227b610/cancel \
  -H "Authorization: Bearer $TSCAPS_API_KEY"

const response = await fetch("https://api.tscaps.io/v1/automation-jobs/9f2c48e1-5b7a-4a29-8874-9dfc8227b610/cancel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TSCAPS_API_KEY}` },
});

const job = await response.json();

import os
import requests

response = requests.post(
    "https://api.tscaps.io/v1/automation-jobs/9f2c48e1-5b7a-4a29-8874-9dfc8227b610/cancel",
    headers={"Authorization": f"Bearer {os.environ['TSCAPS_API_KEY']}"},
)

job = response.json()

Response

Returns 200 OK with the cancelled job record (status: "cancelled").

Create an upload URL

POST /v1/automation-jobs/uploads

Requests a signed URL to upload a video file directly to tscaps cloud storage when the video cannot be exposed over a public URL.

Request parameters

Request example

{
  "fileName": "reel.mp4",
  "sizeBytes": 14205000
}

Code example

curl -X POST https://api.tscaps.io/v1/automation-jobs/uploads \
  -H "Authorization: Bearer $TSCAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "reel.mp4", "sizeBytes": 14205000 }'

const response = await fetch("https://api.tscaps.io/v1/automation-jobs/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TSCAPS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ fileName: "reel.mp4", sizeBytes: 14205000 }),
});

const upload = await response.json();

import os
import requests

response = requests.post(
    "https://api.tscaps.io/v1/automation-jobs/uploads",
    headers={"Authorization": f"Bearer {os.environ['TSCAPS_API_KEY']}"},
    json={"fileName": "reel.mp4", "sizeBytes": 14205000},
)

upload = response.json()

Response

Returns 201 Created with upload instructions:

{
  "uploadId": "3b71d39a-7c22-48a3-92f1-47fae3223019",
  "uploadUrl": "https://storage.tscaps.io/uploads/3b71d39a-...?signature=...",
  "contentType": "video/mp4",
  "sizeBytes": 14205000,
  "expiresAt": "2026-09-12T10:26:38.000Z"
}

Upload the file binary to uploadUrl via HTTP PUT with the returned Content-Length and Content-Type. Once uploaded, pass uploadId to POST /v1/automation-jobs. Read the Direct file uploads guide for complete examples.

List jobs

GET /v1/automation-jobs

Retrieves a paginated list of recent automation jobs for your account, ordered newest first.

Query parameters

Code example

curl "https://api.tscaps.io/v1/automation-jobs?cursor=eyJjcmVhdGVkQXQiOi..." \
  -H "Authorization: Bearer $TSCAPS_API_KEY"

const response = await fetch("https://api.tscaps.io/v1/automation-jobs", {
  headers: { Authorization: `Bearer ${process.env.TSCAPS_API_KEY}` },
});

const { jobs, nextCursor } = await response.json();

import os
import requests

response = requests.get(
    "https://api.tscaps.io/v1/automation-jobs",
    headers={"Authorization": f"Bearer {os.environ['TSCAPS_API_KEY']}"},
)

data = response.json()
jobs = data["jobs"]
next_cursor = data["nextCursor"]

Response

Returns 200 OK:

{
  "jobs": [
    {
      "id": "9f2c48e1-5b7a-4a29-8874-9dfc8227b610",
      "status": "succeeded",
      "phase": "succeeded",
      "templateId": "mira",
      "quotedSeconds": 74,
      "format": "mp4",
      "quality": "high",
      "resolution": { "width": 1080, "height": 1920 },
      "percent": null,
      "downloadUrl": "https://...",
      "outputExpiresAt": "2026-09-19T10:14:00.000Z",
      "failureReason": null,
      "failureCode": null,
      "settledAt": "2026-09-12T10:12:52.000Z",
      "createdAt": "2026-09-12T10:11:38.000Z"
    }
  ],
  "nextCursor": null
}

Failure codes

When a job fails, the response includes:

• failureCode: A machine-readable identifier for program logic.
• failureReason: A human-readable description for debugging or logging.

Always branch on failureCode in your application and include a generic fallback for any future codes:

Billing guarantee

Failed and cancelled jobs never consume automation minutes. Reserved minutes are refunded to your balance immediately.