Tasks

Manage processing tasks

List all tasks

Retrieves a list of tasks for the project, optionally filtered by status or kind.

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Query Parameters

pageinteger

Page number.

Default: 1Minimum: 1

limitinteger

Items per page.

Default: 20Minimum: 1Maximum: 100

statusstring

Filter by task status.

kindstring

Filter by task kind.

Value in:

"ingest" | "workflow" | "speech" | "outline" | "chapters" | "subtitles" | "thumbnails" | "nsfw" | "summary" | "describe" | "video" | "image" | "audio" | "http" | "conditions" | "store" | "prompt" | "tags"

Response Body

A list of tasks.

TypeScript Definitions

Use the response body type in TypeScript.

metaobject

dataarray<object>

linksobject

curl -X GET "https://api.ittybit.com/tasks?page=1&limit=20&status=pending&kind=ingest" \
  -H "Authorization: Bearer <token>"

{
  "meta": {
    "id": "req_listTasksFiltered",
    "status": 200,
    "object": "list",
    "total": 1,
    "page": 1,
    "limit": 20,
    "pages": 1
  },
  "data": [
    {
      "id": "task_abc123",
      "kind": "video",
      "status": "ready"
    }
  ],
  "links": {
    "self": "/tasks?kind=video"
  }
}

Create a new task

Creates a new processing task (e.g., ingest, video transcode, speech analysis) or a workflow task.

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Request Body

application/jsonRequired

Task configuration defining what type of processing to perform. Structure varies based on the task kind.

kindRequiredstring

The type of task to create.

Value in:

"ingest" | "workflow" | "speech" | "video" | "image" | "audio" | "summary" | "describe" | "chapters" | "outline" | "subtitles" | "nsfw" | "thumbnails"

urlstring

URL of the source file (required for 'ingest' kind unless file_id is used, can be used for others).

Format: "uri"

inputobject

Task-specific input parameters depending on the kind of task.

file_idstring

ID of an existing file to use as input (alternative to url).

workflowarray<object>

An array of task definition objects for a workflow.

webhook_urlstring

An optional HTTPS URL to send a webhook notification to upon task completion or failure.

Format: "uri"

filenamestring

Desired filename for the output (if applicable).

folderstring

Desired output folder (if applicable).

formatstring

Output format (e.g., for video/image tasks).

widthinteger

Output width (for video/image tasks).

heightinteger

Output height (for video/image tasks).

qualityinteger

Output quality setting (e.g., for video/image tasks, 0-100).

Response Body

Created task (Deprecated endpoint)

TypeScript Definitions

Use the response body type in TypeScript.

metaobject

dataobject

linksobject

curl -X POST "https://api.ittybit.com/tasks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    "filename": "bunny-1280x720.mp4",
    "folder": "examples/cartoons",
    "width": 1280,
    "height": 720
  }'

{
  "id": "task_newOldStyle",
  "kind": "ingest",
  "status": "waiting"
}

Get task by ID

Retrieves the details of a specific task by its ID.

Authorization

AuthorizationRequiredBearer <token>

Requires a Bearer token in the Authorization header. Format: Authorization: Bearer YOUR_API_KEY

In: header

Path Parameters

idRequiredstring

The ID of the task to retrieve.

Response Body

Task details.

TypeScript Definitions

Use the response body type in TypeScript.

metaobject

dataobject

linksobject

curl -X GET "https://api.ittybit.com/tasks/string" \
  -H "Authorization: Bearer <token>"

{
  "meta": {
    "id": "req_ghi789jkl012",
    "method": "GET",
    "url": "/tasks/task_53mex413do7UOzxK",
    "version": "2024-03-21",
    "status": 200,
    "org_id": "org_01J9QT9Q853B3P8PV33G8FR0YZ",
    "project_id": "prj_43b8xt37gTWV",
    "object": "task",
    "created": "2025-04-25T12:10:00.123Z"
  },
  "data": {
    "id": "task_53mex413do7UOzxK",
    "object": "task",
    "kind": "ingest",
    "input": null,
    "options": {
      "url": "http://commondatastorage.googleapis.com/.../ElephantsDream.mp4",
      "filename": "elephant.mp4"
    },
    "output": {
      "id": "file_53mexc77Rzty11fP",
      "object": "source",
      "kind": "video"
    },
    "status": "ready",
    "progress": 100,
    "error": null,
    "created_by": null,
    "created": "2025-04-23T14:33:04.140Z",
    "updated": "2025-04-23T14:34:08.411Z",
    "next": []
  },
  "links": {
    "self": "https://api.ittybit.com/tasks/task_53mex413do7UOzxK"
  }
}

Example of a completed ingest task