Talonic

List the saved schemas in the workspace as compact summaries (id, short_id, name, description, version, field_count). USE WHEN: 'what schemas do I have', or to find a reusable schema before extracting. NOT FOR: a one-off extraction with an inline schema (call talonic_extract directly). ARGS: none. RETURNS: data[] of schema summaries. Full field definitions are omitted here — read the talonic://schemas resource for those. Pass a schema's id/short_id to talonic_extract as `schema_id`.

Takes no parameters.

Save a reusable schema to the workspace for use across future extractions. USE WHEN: the user confirms a schema/template they want to reuse across documents. NOT FOR: a single one-off extraction (pass the schema inline to talonic_extract instead). ARGS: `name`; `definition` — a JSON Schema ({type:'object',properties:{...}}) or a flat {field:'type'} map. RETURNS: the saved schema with id and short_id. Pass either to talonic_extract as `schema_id`.

Fetch a single document's metadata and processing status from the workspace. USE WHEN: 'tell me about document X', or to poll status after talonic_request_upload until the file is ready. NOT FOR: full text (use talonic_to_markdown) · extracted fields (use talonic_extract). BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this. ARGS: document_id. RETURNS: filename, pages, type_detected, language, and `status`. Status lifecycle: pending_upload -> uploading -> queued -> extracting -> completed. Wait for `completed` before calling talonic_extract on a freshly uploaded doc. Terminal failure statuses: ocr_failed, extraction_failed, error — stop polling and report the failure to the user if any of these appear. To read the document's text, call talonic_to_markdown with this id.

Find documents, fields, schemas, or sources in the workspace. One call returns ranked results across all types. MATCHING IS LITERAL KEYWORD, not semantic. Query with ONE short SINGULAR term or an exact filename: 'invoice', 'bank statement', 'sample-invoice.pdf'. Sentences ('documents related to invoices') and plurals ('invoices') return empty. If a search comes back empty, retry with a shorter singular keyword before concluding the workspace has nothing. USE WHEN: the user names or describes a document without an id, or you need a document_id or a filterable field name before extract / to_markdown / get_document / filter. NOT FOR: structured field-value filters like 'amount > 1000' (use talonic_filter). ARGS: query (short literal keyword); optional limit. RETURNS: documents[], fields[]/fieldMatches[] (only `filterable: true` entries work in talonic_filter), schemas[], sources[]. Use the id from documents[] to act on a named file.

Find documents by their extracted field VALUES using composable conditions (e.g. 'invoices where total > 1000'). USE WHEN: value-based criteria on extracted fields — numeric/date/text comparisons or presence checks. NOT FOR: free-text / concept search (use talonic_search) · a single document by id (use talonic_get_document). ARGS: conditions[] (AND-ed). Each = EXACTLY ONE of `field` (canonical name) or `field_id` (UUID), an `operator`, and usually a `value`. Operators: eq, neq, gt, gte, lt, lte, between (needs `value` AND `value_to`), contains, is_empty / is_not_empty (no value). `value`/`value_to` are string|number|boolean matching the field type (ISO YYYY-MM-DD for dates). TEXT FILTERS: for eq/contains/is_not_empty on a text field, just TRY a natural field name ('currency', 'vendor_name') — names resolve server-side and an unresolved field surfaces in warnings[] rather than erroring. Do NOT block on discovering the field first; search-first is only required for numeric operators. NUMERIC GUARD: gt/gte/lt/lte/between only work when the field's dataType is 'number'. Call talonic_search first and check dataType; a numeric op on a string field returns zero matches. If the response has `warnings[]`, surface them to the user — do not silently retry. RETURNS: data[] (matching documents with field values), total, warnings[].

Get the OCR-converted markdown text of a document. USE WHEN: the user wants the full text — 'what does it say', summarise, or translate a document. NOT FOR: specific structured fields (use talonic_extract with a schema). BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this. ARGS: prefer `document_id` (a workspace doc — one cheap call). Otherwise `file_url`, or `file_data`+`filename` for small local files — provide exactly one. A file input ingests the document first and consumes credits; `document_id` does not. RETURNS: document_id and markdown (the full text).

Extract structured, schema-validated JSON from a document: PDF, scan, image, DOCX, email, or photo. Returns the requested fields with per-field confidence scores and, with include_provenance, the page and source text each value came from. USE WHEN: the user asks to extract data from a document, turn a PDF into JSON, pull fields from a file, or parse a scan / form / statement / receipt / report, for common (invoice, contract) or unusual document types. NOT FOR: full plain text (use talonic_to_markdown) · finding documents (use talonic_search / talonic_filter). BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this. ARGS: define the fields you want with inline `schema` (JSON Schema, e.g. {type:'object',properties:{vendor_name:{type:'string'}}}) OR a saved `schema_id`, not both. Don't know the fields yet? Set `auto_schema:true` to let Talonic discover them (open capture) and return a suggested schema you can refine. Provide EXACTLY ONE document source: `document_id` (cheapest, a workspace doc), `file_url` (public URL), or `file_data`+`filename` (small local files only). COST: each call uses credits; talonic_get_balance shows the remaining balance. RETURNS: data (the JSON), confidence.overall and confidence.fields (treat <0.7 as needs review), provenance per field when include_provenance is set, document metadata, extraction_id.

Read the workspace's Talonic credit balance, EUR value, tier, 30-day burn, and projected runway. USE WHEN: the user asks about credits/budget, or before a large batch when you want to confirm headroom. NOT FOR: the per-call cost of a single extraction (that is on the talonic_extract response). ARGS: none. RETURNS: balance_credits, balance_eur, tier, burn_rate_30d_credits, projected_runway_days (-1 = no recent usage), tier_resets_at.

Takes no parameters.

Read Talonic's machine-readable credit pricing catalog: fixed per-unit rates so you can predict spend BEFORE running anything. USE WHEN: estimating the cost of a planned extraction/structuring/matching job, or answering a pricing question. Public — works without spending credits. NOT FOR: the workspace's current balance (use talonic_get_balance) or what it has already spent (use talonic_get_usage). ARGS: none. RETURNS: currency, credits_per_eur, multipliers (e.g. batch 0.5x), and units[] — each { unit, label, credits, eur, free }.

Takes no parameters.

Read the workspace's per-function credit consumption over a trailing window: where the credits actually went. USE WHEN: the user asks what they have spent credits on, or you want to see which function (extraction, structuring, intelligence ops) dominates spend. NOT FOR: the remaining balance (use talonic_get_balance) or per-unit rates (use talonic_get_pricing). ARGS: days (optional, default 30, clamped 1-365). RETURNS: period_days, total_credits, and by_function[] — each { operation_type, operations, credits }, highest spend first.

Get a browser upload link the user opens to add a file to their workspace. Returns the link plus a pre-allocated document_id. USE WHEN: the user wants to upload a document and you cannot pass it directly: the client cannot attach file bytes to a tool call, or the file is too large for tool-call arguments. NOT FOR: a document already in the workspace (use its document_id) · a file already on a public URL (use file_url on talonic_extract). ARGS: filename (with extension). RETURNS: upload_url, document_id, expires_at. After the user uploads, poll talonic_get_document on that document_id until status is 'completed', then call talonic_extract. If status becomes ocr_failed, extraction_failed, or error, stop polling and report the failure to the user.

List the workspace's Field Registry — the canonical concepts Talonic has discovered across every ingested document, each with a stable id, maturity level, data type, synonyms and occurrence count. USE WHEN: you need to know WHAT data exists before querying it, want to pick the right concept for a question, or need the exact field id for talonic_get_field / talonic_field_values. NOT FOR: locating a specific document (talonic_search) or filtering documents by a value (talonic_filter). ARGS: `search` (case-insensitive contains on name), `maturity` (core | proven | candidate — prefer `core`/`proven` for anything you will build on), `include_superseded` (default false: rows merged into another concept are hidden so you never see two ids for one concept), `limit`, `cursor`. RETURNS: data[] of { id, canonical_name, display_name, data_type, maturity, tier, synonyms, description, occurrence_count, superseded_by, links } plus cursor pagination.

Get the CONCEPT CARD for one Field Registry field: what it means (curated description + extraction instruction), its synonyms and aliases, maturity, where it occurs (document/occurrence counts, first/last seen, document-type spread), its value distribution (top values with counts, distinct count, examples), schema usage, and identity links (superseded_by, absorbed concepts). USE WHEN: you must decide whether a field is the right concept for a question, need example values or the value shape before writing a filter, or hold a field NAME from the user and need the live concept behind it. NOT FOR: listing many fields (talonic_list_fields) or reading every value (talonic_field_values). ARGS: exactly one of `field_id` or `name`. Names are resolved through canonical name → spelling fold → merge aliases → synonyms (then case-insensitive fallbacks) and followed to the live concept; the response says which arm matched. `include_history: true` appends the curation trail (merges, renames, maturity moves). RETURNS: the card { id, canonical_name, maturity, data_type, definition, identity, occurrence, values, usage, links } plus `resolution` when a name was given and `history` when requested.

Read a field's CURRENT VALUES across documents, with provenance — one row per bound occurrence: document id + filename + type, the value, confidence, the raw name it was captured under, the verbatim source text, and the resolution band that bound it. USE WHEN: the user asks 'what are all the X across my documents', you need to tabulate or aggregate one concept across the corpus, or you want the evidence (source text + document) behind a value. NOT FOR: multi-field row-shaped queries over documents (talonic_filter) or one document's full field set (talonic_get_document). ARGS: exactly one of `field_id` or `name`; optional `document_id` (one document), `value` (case-insensitive contains filter), `limit` (max 100), `cursor`. RETURNS: { field_id, canonical_name, concept_ids, data[] of { occurrence_id, document_id, document_filename, value, confidence, provenance{ raw_field_name, source_text, resolved_by, needs_confirmation, via_redirect }, links }, pagination }. Rows are Sources-IAM filtered for the caller.

Locate the REAL data behind a natural-language concept before querying anything: semantic + lexical retrieval that resolves a phrase ('payment volume per transaction', 'counterparty', 'Vertragslaufzeit') to the registry fields, values, documents and text passages that carry it — even when the field is captured under a different name. USE WHEN: the user asks about a concept and you are not sure which field holds it, when talonic_list_fields / talonic_search came back empty or ambiguous, or when the answer may live in document prose rather than a captured cell. NOT FOR: reading a known field's values (talonic_field_values) or filtering by a known field (talonic_filter). ARGS: `query` (the concept, in the user's words), optional `top_k` (1–25, default 10), `document_ids` (hard scope). RETURNS: ranked planes — FIELDS (canonical_name, field ids/keys, maturity/tier, occurrence_count, sample values with their documents), VALUES, DOCUMENTS and PASSAGES — every item a ready handle for the next call. Read-only, no LLM cost.

List the platform's agent tool registry — every retrieval, provenance and analysis primitive the in-product Talonic agent runs on (find_data, describe_data, query_data for read-only SQL over the extracted data, get_document_markdown, workspace_overview, …) with its input schema and whether THIS credential may invoke it. Target API: https://talonic.com/docs/api (GET /v1/agent/tools). USE WHEN: you want a capability talonic_* tools do not cover directly (e.g. SQL over the structured data, a workspace overview, cohort discovery) — list here, then call talonic_invoke_agent_tool with the tool name and its args. NOT FOR: discovering fields (talonic_list_fields / talonic_find_data) or documents (talonic_search) — those are shaped for you. ARGS: `only_invocable` (default true — hide tools this credential cannot run), `include_schemas` (default true — include each tool's JSON input schema). RETURNS: { tools[] of { name, description, impact, capability, can_invoke, input_schema? }, invocable_count, totalCount }.

Invoke ONE named tool from the platform's agent tool registry directly, with no model in the loop — you choose the arguments. This is how an external agent uses Talonic's retrieval and provenance while driving control flow itself (e.g. `query_data` for a read-only SQL SELECT over the extracted data, `describe_data` for the queryable field list, `get_document_markdown` to read a document's text). READ-ONLY FOR EVERY CREDENTIAL: the platform runs each caller of this route, API key or OAuth session alike, as its least-privilege viewer role, which grants only the registry's read-only tools (capability `data.read`). Write-capable registry tools are never invocable here, however you connected, so this tool reads and never changes workspace data. Target API: Talonic agent tool registry — https://talonic.com/docs/api (POST /v1/agent/tools/{name}/invoke; input schemas from talonic_list_agent_tools). USE WHEN: talonic_list_agent_tools showed a tool with can_invoke: true that does what you need. Pass exactly the `args` its input_schema declares. NOT FOR: anything a dedicated talonic_* tool already does (prefer those — they are shaped for you). ARGS: `name` (tool name), `args` (object matching the tool's input_schema), optional `document_ids` (hard scope for scope-aware tools). RETURNS: { tool, result (the tool's parsed output), citations?, artifacts?, cards? }. Denied capabilities come back as an error naming the capability required; the platform re-checks every call.

List Agent-stage tasks visible to this Talonic workspace credential. USE WHEN: looking for external-agent work to process; begin with status 'available'. To take a batch of one pipeline (e.g. 'take 10 tasks of pipeline X'), list with pipeline_id and status 'available', then claim each with talonic_claim_agent_task; a task another agent took returns HTTP 409, so skip it and take the next. NOT FOR: reading the immutable task payload (use talonic_get_agent_task) or taking a lease (use talonic_claim_agent_task). ARGS: optional status, pipeline_id, limit, and cursor. RETURNS: metadata only plus pagination.next_cursor.

Fetch one Agent-stage task's immutable input snapshot, instructions, and declared output contract. This disclosure is audited. USE WHEN: inspecting a listed task before deciding whether to process it. NOT FOR: acquiring the task (use talonic_claim_agent_task) or returning results (use talonic_submit_agent_task). ARGS: task_id. RETURNS: metadata, input_snapshot, output_contract, instructions, and timeout_fallthrough.

Claim an available Agent-stage task, or reclaim it after its lease expires. USE WHEN: ready to process a task. Save the returned execution_epoch and lease_expires_at. NOT FOR: merely inspecting work (use talonic_get_agent_task) or extending an active lease (use talonic_heartbeat_agent_task). A conflicting live claim returns HTTP 409. A successful claim returns the task payload: input_snapshot, instructions, and output_contract, whose entries carry each field's Spec rules (description) and allowed codes (enumValues). Review the documents against those rules.

Extend the lease on a claimed Agent-stage task. USE WHEN: processing may continue past lease_expires_at; heartbeat before expiry using the epoch from claim. NOT FOR: acquiring a task (use talonic_claim_agent_task) or submitting finished outputs (use talonic_submit_agent_task). ARGS: task_id and execution_epoch. Stale or foreign claims return HTTP 409.

Submit declared output fields for a claimed Agent-stage task and resume the parked document. USE WHEN: processing is complete and every required output in output_contract is ready. NOT FOR: undeclared fields or partial lease maintenance (use talonic_heartbeat_agent_task). ARGS: task_id, execution_epoch, outputs keyed exactly by declared field key, and optional summary. The platform validates all fields and types transactionally before writing anything.

List the workspace's Specs — the configured pipelines (rail + fields) that talonic_run_spec executes. Each row: id, name, description, schema_id (the schema a run materializes onto — a DIFFERENT id from the Spec's), version / materialized_version (null = never published), field_count, node_count, timestamps. USE WHEN: the user wants to run 'their pipeline' / 'the invoice Spec', or you need a spec_id for talonic_run_spec / talonic_get_spec. NOT FOR: ad-hoc extraction schemas (talonic_list_schemas) or discovering fields (talonic_list_fields). ARGS: optional `search` (name contains, case-insensitive), `limit` (1–100, default 20), `cursor` (from pagination.next_cursor), `order` (asc|desc by updated_at). RETURNS: { data[] of { id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, created_at, updated_at, links }, pagination { total, limit, has_more, next_cursor } }.

Get one Spec's structure: identity and version state, the schema it materializes onto, `nodes[]` (the rail as authored, in editing order) and `phases[]` (the compiled execution plan, in run order — a validation checkpoint expands to one phase per gate, so the two lists differ on purpose), and `fields[]` (Spec field ↔ schema field). USE WHEN: you need to explain what a run will do, confirm a Spec is published (`version` non-null) before talonic_run_spec, or map field names to keys. NOT FOR: listing Specs (talonic_list_specs) or starting a run (talonic_run_spec). ARGS: `spec_id` (UUID from talonic_list_specs); optional `include_versions` (adds `versions[]` — published versions newest first, each { version, content_hash, created_at, is_materialized }). RETURNS: the Spec object { id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, schema, nodes[], phases[], fields[], links } plus optional versions[].

Run a Spec — the customer's configured pipeline — over documents, in one call. Two inputs: `document_ids` (documents already in the workspace; for a new file, first talonic_request_upload → poll talonic_get_document until completed) OR `file_urls` (public https files, max 20; Talonic ingests them first). Consumes credits. USE WHEN: the user wants to 'run the invoice pipeline on these documents', process files through their Spec, or produce the Spec's structured rows. NOT FOR: one-off extraction with an ad-hoc schema (talonic_extract), or checking progress (talonic_get_run) / reading rows (talonic_get_run_results). ARGS: `spec_id` (talonic_list_specs); exactly one of `document_ids[]` (1–500) or `file_urls[]` (1–20, https); optional `name`, `pipeline_mode` (`new` default | `append` to the Spec's existing pipeline); `batch_id` and flat `metadata` only with file_urls. RETURNS: RunEnvelope { run_kind ('pipeline'|'run'), run_id, pipeline_id, spec_id, status ('processing'|'completed'|'failed'), raw_status, input_count, documents?, message?, links }. Then poll talonic_get_run with the `pipeline_id` when run_kind is 'pipeline', or with the `run_id` when it is 'run', every 5–10 s until status is completed/failed, then talonic_get_run_results.

Poll a Spec run started by talonic_run_spec: normalised status plus document-level progress and, for pipelines, per-phase progress. USE WHEN: waiting for a run to finish — poll every 5–10 s; stop on `completed` or `failed`. NOT FOR: reading the structured rows (talonic_get_run_results) or starting a run (talonic_run_spec). ARGS: exactly one of `pipeline_id` (run_kind 'pipeline') or `run_id` (run_kind 'run'), from the RunEnvelope. RETURNS: { run_kind, run_id, pipeline_id, spec_id, status, raw_status, input_count?, progress { total_documents, completed_documents, error_documents, phases?[] }, documents?[], error_message?, created_at, updated_at }.

Read a Spec run's structured rows — one row per document with the Spec's fields as clean values (held/pending-review cells serialize null), plus the column definitions. USE WHEN: talonic_get_run reports `completed` (partial rows are also readable while `processing`). NOT FOR: progress (talonic_get_run) or per-field provenance of a single value (include: ['provenance'] here, or talonic_field_values). ARGS: exactly one of `pipeline_id` (run_kind 'pipeline', optionally with the envelope's `run_id` to scope to that submission) or `run_id` alone (run_kind 'run'); optional `document_id` (one document), `include` (['cells','provenance'] — heavier payload), `limit` (1–200, default 50), `cursor`. RETURNS: { run_kind, status, columns[] of { field_key, display_name, data_type }, data[] of { document_id, filename, record_id, status ('complete'|'partial'|'error'|'processing'), completed_at, fields { field_key: value }, cells?, provenance? }, pagination, pending_review_count, links }.

Ask a natural-language question over the workspace's documents and get a cited, verified answer (markdown). The Talonic agent plans over the structured field plane, runs read-only SQL over extracted cells, reads document text, and grounds every load-bearing claim in a source span. Consumes credits. USE WHEN: the user asks an open question about their documents ('which vendors invoiced us twice in May?'), wants a summary across documents, or the answer needs reasoning over several fields. NOT FOR: reading a known field's values (talonic_field_values, free) or filtering documents by a known value (talonic_filter, free); locating which field holds a concept (talonic_find_data). ARGS: `question`; optional `scope` { document_ids[], schema_id, pipeline_id, data_product_id, document_type, source_id, tags[], ingested_after, ingested_before } (ANDed), `conversation_id` (continue a thread), `output_format` { instruction, template }, `wait_seconds` (0–55, default 45). RETURNS: { ask_id, status ('completed'|'processing'|'error'), conversation_id, answer (markdown), citations[] { quote, document_id, kind, filename, app_url }, verification { verdict, checks_total, checks_unsupported, correction }, usage { tokens, credits_charged }, tool_calls, artifacts[], waited_ms }. If status is still 'processing' after the wait, call talonic_get_answer with the ask_id.

Poll an ask started by talonic_ask that was still processing when the wait ended. USE WHEN: talonic_ask returned status 'processing' with an ask_id — poll every few seconds until 'completed' or 'error'. NOT FOR: asking a new question (talonic_ask). ARGS: `ask_id`. RETURNS: the same answer envelope as talonic_ask (answer, citations[], verification, usage) or { status: 'processing', poll_hint }.

List one External-mode app's decision tasks (runs parked for an outside agent to decide), newest first. USE WHEN: looking for decisions to make for an app; begin with status 'available'. This is the polling alternative to the app.decision_task.offered webhook. NOT FOR: Agent-stage document tasks (use talonic_list_agent_tasks), reading a task's input package (claim it, then talonic_read_decision_package), or taking a lease (talonic_claim_decision_task). ARGS: app_id, optional status, limit, cursor. RETURNS: task metadata only (id, run_id, status, execution_epoch, lease and sla_deadline_at timing) plus pagination.next_cursor. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

Claim an available decision task (or reclaim one whose lease expired) and receive the decision bundle: task metadata with the new execution_epoch, output_contract, precedents, and a package descriptor { package_kind, record_count, page_size, first_cursor, documents }. USE WHEN: ready to decide a listed task. There is no separate get: claiming IS the payload fetch. Save execution_epoch and lease_expires_at; then read the records with talonic_read_decision_package starting at first_cursor (null means the package has no records). NOT FOR: extending a live lease (talonic_heartbeat_decision_task) or returning a decision (talonic_submit_decision_task). A conflicting live claim returns HTTP 409. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

Read one page of a claimed decision task's frozen input package: the records the decision must be made from, with their provenance locators. Only the current claimant may read it; each page read is journaled onto the run. USE WHEN: after a successful claim, walking pages from package.first_cursor while pagination.has_more is true. The first page also carries the source documents list. A mining_round package is one record { system_prompt, first_turn, tools }. NOT FOR: unclaimed tasks (HTTP 409; claim first) or listing tasks (talonic_list_decision_tasks). ARGS: task_id, optional cursor and limit (1 to 2000). Copy evidence locators verbatim from these records for the submit. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

Extend the lease on a claimed decision task, never past its sla_deadline_at. USE WHEN: deciding may run past lease_expires_at; heartbeat before expiry using the epoch from claim. NOT FOR: acquiring a task (talonic_claim_decision_task) or finishing one (talonic_submit_decision_task / talonic_release_decision_task / talonic_fail_decision_task). ARGS: task_id and execution_epoch. A stale or foreign epoch returns HTTP 409: stop, discard the work, and re-list. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

Submit the decision for a claimed decision task; the platform verifies it transactionally and resumes the run. USE WHEN: the decision is final. outcome must satisfy output_contract from the claim (plain JSON Schema, or the verdict_matrix / record_set envelope), evidence lists the package locators relied on (verbatim; [] only if the app allows unevidenced decisions), rationale is a short summary. Rejections are HTTP 422 with the reason and change nothing; the task stays claimed under your epoch, so fix and resubmit before the lease ends. NOT FOR: giving the task back undecided (talonic_release_decision_task) or declaring it undecidable (talonic_fail_decision_task). Stale epoch is HTTP 409. ARGS: task_id, execution_epoch, outcome, evidence, rationale, optional confidence and service_version. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

Release a claimed decision task back to 'available' without deciding it; the next claim bumps the epoch. USE WHEN: you cannot finish within the lease or SLA but another claimant could decide it. NOT FOR: declaring the task undecidable (talonic_fail_decision_task, which raises a review and applies the app's fallback) or keeping the lease (talonic_heartbeat_decision_task). ARGS: task_id and execution_epoch. Stale epoch is HTTP 409. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.

Report that the claimed decision task cannot be decided: raises a Human Review with your reason AND applies the app's declared fallback policy (rules decide, hold for review, or fail the run). USE WHEN: the package is insufficient or contradictory and no claimant could decide it. This ends the task (status 'failed'). NOT FOR: temporary give-backs (talonic_release_decision_task) or a decision you can make with low confidence (submit it with confidence set). ARGS: task_id, execution_epoch, reason (up to 2,000 characters). Stale epoch is HTTP 409. AUTH: a tlnc_ key needs a per-app 'decide' grant; an OAuth connector session needs the apps:decide scope (consented at connect) and a live workspace role of senior_member or above. A 403 (decide_grant_required, insufficient_scope, insufficient_tier) names what is missing — tell the user, do not retry.