Tools reference

Submit a video, poll the job, and cancel it if needed. extract reuses the same admission and queue path as POST /v1/jobs, so a backpressure error like CONCURRENT_JOBS_LIMIT or COST_QUOTA_EXCEEDED surfaces to the agent as a structured tool error.

Submit a video for extraction into structured JSON. Optionally apply a saved schema by id, or pass an inline JSON Schema (the two are mutually exclusive). Returns immediately with a job_id; the job runs asynchronously, so poll it with get_job until the status is succeeded.

Look up an extraction job by id. Returns its status (queued, running, succeeded, failed, or cancelled) and, once succeeded, the full typed extraction result inline. This is the tool to poll after extract.

Cooperatively cancel a queued or running job. It stops the workflow and frees the tenant's concurrency slot. Idempotent on an already-cancelled job; returns JOB_ALREADY_TERMINAL if the job already succeeded or failed.

Read what a succeeded job left behind, the knowledge graph, the evidence chain, and the raw per-job artifacts, so an agent can answer follow-up questions and cite the source without re-extracting. Every artifact tool takes the same job_id.

Fetch the diarized ASR transcript for a succeeded job: full text, per-segment timing, and speakers. Use it to answer verbatim questions and quote the source. Returned in full (a very long transcript may exceed some clients' tool-result caps).

Fetch the deduped frame inventory Pass A reasoned over. For each frame: the id, the source_ref (a frame#NNNNNN ref matching get_evidence spans), timestamp, cluster, and pHash. Metadata only, no image bytes.

Fetch the VLM description of each kept frame (what is on screen), anchored to the frame timestamp. Use it for visual questions such as what text was on a slide at a given moment. An audio-only job returns visual_branch: "absent" with no frames, which is not an error.

Fetch the Pass A knowledge graph for a succeeded job: nodes (entities and timestamped claims drawn from the video) and edges (relations between them). Traverse it in-conversation to answer follow-up questions, no re-extraction needed. Defaults to the compact view; pass view: "canonical" for the full graph.

Fetch the evidence spans for a succeeded job. For each extracted value: where it came from, the modality (audio, visual, or both), the (t_start, t_end) source moment, the source ref (transcript segment or video frame), and the knowledge-graph node id. Use it to cite or verify where a fact in the result originated.

Discover, inspect, and register reusable extraction schemas. A schema is a JSON Schema describing the typed output you want; apply one by passing its id to extract.

Register a reusable extraction schema the workspace can apply to future jobs via extract(schema_id). The JSON Schema is validated at registration time. Returns the new schema_id. For a one-off shape, pass schema_inline to extract directly instead.

Fetch one saved schema's full JSON Schema body. (list_schemas only returns id, name, and description.) Use it to inspect the exact fields a schema defines before applying it via extract(schema_id).

Browse the tenant's saved schemas and the shipped template library. Returns the id, name, description, and is_template for each. No input parameters. Pass a returned id to extract to apply it.

Discover recent jobs and delivery targets, and push a finished result to a webhook destination.

List the most recent extraction jobs for the workspace (newest first, up to 25). Use it to discover job ids to pass to get_job, get_graph, get_evidence, or deliver.

List the workspace's configured destinations (id, name, type, status). Use it to discover a destination_id to pass to deliver. No input parameters. Secrets and config are never returned.

Push a succeeded job's extraction result to one of the tenant's webhook destinations. Lirovo signs it (HMAC-SHA256) and retries with backoff. Returns a delivery_id; the delivery runs asynchronously. The job must have succeeded, and destination_id must be an existing webhook destination.

On failure a tool returns an error result whose payload mirrors the REST error envelope: { error: { code, message } }. The codes are the same stable enum the API uses, so an agent can switch on, for example, JOB_NOT_FOUND, SCHEMA_NOT_FOUND, SOURCE_BLOCKED, or COST_QUOTA_EXCEEDED and back off.