lirovo/ docs
Get startedAPI referenceSDKMCPArchitecture
API reference

Jobs

A job is one run of the extraction pipeline on one source video. Submit a job with a source URI and a schema, poll for status, then read back the typed result.

Create a job#

POST/v1/jobs
Submit a job. Accepts an optional Idempotency-Key header and an optional X-Lirovo-Model-Stack header to override model routing. Returns 202 with the queued job.

Provide a source URI and either a registered schema_id or an inline schema_inline (the two are mutually exclusive; sending both returns 422 CONFLICTING_SCHEMA_REF). The job is accepted with 202 and processed asynchronously.

source_urirequired
string (uri)

URL of the source video. Must resolve to a supported source.

schema_id
string | null

A registered schema id (sch_...). Mutually exclusive with schema_inline.

schema_inline
object | null

An inline JSON Schema. Mutually exclusive with schema_id.

destination_ids
string[]

Up to 10 destination ids to push results to once succeeded.

webhook_url
string (uri) | null

Receive a POST when the job reaches a terminal state.

bash
curl -X POST https://api.lirovo.ai/v1/jobs \
  -H "Authorization: Bearer $LIROVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "schema_id": "sch_a1b2c3"
  }'

List jobs#

GET/v1/jobs
List the tenant's jobs. Supports limit (1 to 100, default 25), cursor, and a status filter. Returns { data, next_cursor }.

The status filter accepts one of queued, running, succeeded, failed, or cancelled. Pass the opaque next_cursor from a previous response as cursor to page forward.

bash
curl "https://api.lirovo.ai/v1/jobs?status=succeeded&limit=25" \
  -H "Authorization: Bearer $LIROVO_API_KEY"

Get a job#

GET/v1/jobs/{id}
Get one job's status. Returns the full job object. 404 if it does not exist for this tenant.

Job object

idrequired
string

Job id, e.g. job_x9k2m4.

statusrequired
string

One of queued, running, succeeded, failed, cancelled.

current_stage
string | null

The pipeline stage currently running.

source_typerequired
string

One of youtube, vimeo, loom, s3, upload, url.

source_urirequired
string (uri)

The submitted source URL.

source_duration_s
number | null

Source duration in seconds, once probed.

schema_id
string | null

The schema used, if registered.

extraction_id
string | null

Present once succeeded, e.g. ext_7p4q2r.

error_code
string | null

Set on failed or cancelled jobs.

error_message
string | null

Human-readable failure reason.

webhook_url
string (uri) | null

The webhook URL, if one was provided.

created_atrequired
string (date-time)

Submission timestamp.

started_at
string (date-time) | null

When processing began.

finished_at
string (date-time) | null

When the job reached a terminal state.

bash
curl https://api.lirovo.ai/v1/jobs/job_x9k2m4 \
  -H "Authorization: Bearer $LIROVO_API_KEY"

Cancel a job#

POST/v1/jobs/{id}/cancel
Cancel a queued or running job. Cooperatively terminates the workflow and flips the job to cancelled with error_code=CANCELLED. Returns 200 with the updated job.

Cancel is idempotent: re-cancelling an already-cancelled job returns 200 with the existing state. A job already in a different terminal state (succeeded or failed) returns 409 JOB_ALREADY_TERMINAL: cancel does not apply.

bash
curl -X POST https://api.lirovo.ai/v1/jobs/job_x9k2m4/cancel \
  -H "Authorization: Bearer $LIROVO_API_KEY"

Get the result#

GET/v1/jobs/{id}/result
Get the typed extraction once the job has succeeded. Returns 404 JOB_RESULT_NOT_READY if the job has not yet succeeded, or 404 JOB_NOT_FOUND if it does not exist.

Job result object

job_idrequired
string

The job this result belongs to.

extraction_idrequired
string

The extraction id, e.g. ext_7p4q2r.

schema_id
string | null

The schema the output conforms to.

resultrequired
object

The typed JSON output. Shape is tenant-defined by the job's schema.

validation_statusrequired
string

One of clean, repaired, partial, failed.

model_used
string | null

The model that produced the result.

tokens_in
integer | null

Prompt tokens consumed.

tokens_out
integer | null

Completion tokens produced.

cost_cents
number | null

Cost of the run in cents.

created_atrequired
string (date-time)

When the result was written.

bash
curl https://api.lirovo.ai/v1/jobs/job_x9k2m4/result \
  -H "Authorization: Bearer $LIROVO_API_KEY"

Delete a job#

DELETE/v1/jobs/{id}
Soft-delete a terminal job. Sets deleted_at and keeps the row so artifacts and evidence keep their foreign keys; every read path then treats the resource as gone. Idempotent; returns { id, deleted_at }.

Refuses with 409 JOB_NOT_TERMINAL on queued or running jobs: cancel first, or wait for the workflow to finish.

bash
curl -X DELETE https://api.lirovo.ai/v1/jobs/job_x9k2m4 \
  -H "Authorization: Bearer $LIROVO_API_KEY"