Jobs and tasks

Operations

Each task has an operation and, except for imports, names its inputs.

• import/url - the server fetches an http(s) URL. Add filename to override the name.
• import/base64 - inline upload: file (base64) and filename.
• Any tool slug from the catalog - takes input plus that tool's options.
• export/url - makes the files of its input tasks downloadable through signed URLs.

A job holds up to 20 tasks. The graph is validated at create time: unknown operations, unknown option names, wrong option types, missing required options, references to tasks that do not exist, and cycles are all rejected with an error naming the exact task and field.

States

Tasks move waiting, processing, then finished, error or cancelled. The job mirrors them: it is finished only when every task finished. One failed task fails the job and cancels its remaining waiting tasks. Failed tasks carry an error code and a message that names the file or option at fault.

Endpoints

POST   /v1/jobs             create (201, or 200 on an Idempotency-Key replay)
GET    /v1/jobs             list recent, ?status= and ?limit=
GET    /v1/jobs/{id}        current state
GET    /v1/jobs/{id}/wait   long-poll until settled (~55 s max per call)
DELETE /v1/jobs/{id}        cancel and delete every file immediately
GET    /v1/tasks/{id}       one task
GET    /v1/files/{id}       file metadata plus a fresh signed URL
DELETE /v1/files/{id}       delete now, deletion verified

Idempotency

Send an Idempotency-Key header on create. A retry with the same key returns the job made the first time instead of running the work twice. Keys are per account, up to 200 characters.

Retention

retention_s (0 to 86400, default 3600) starts when the job finishes. After it, files are deleted, deletion is verified against the store, and an audit row records it. Zero means one download or 60 seconds, whichever comes first. DELETE the job or the file to purge earlier.

Quotas and sandbox

The free plan runs 1,000 tool tasks a month, 5 jobs at a time, files up to 100 MB. Import and export tasks are free. Keys created as sandbox (gk_test_) run the same pipeline with nothing counted, files up to 10 MB and retention capped at 15 minutes. Limits and usage show in the dashboard.