talonic_ap_bills
ChatGPTList AP invoices as posting-ready vendor bills, each with vendor, invoice number, dates, amount (as invoiced and in the ledger currency), entity, status, holds with dollars and evidence, NetSuite mapping and lines. USE WHEN: looking up invoices by vendor or number, or listing the ready or held ones. NOT FOR: totals (talonic_ap_overview). ARGS: status ready|held, entity (entity code), reason above_contract|duplicate|missing_po|vendor_unknown, query (vendor, number, filename or contract contains), limit (default 500). RETURNS: { currency, total, data[] }.
talonic_ap_config
ChatGPTRead the AP configuration: which captured document kinds are bills, the contract register used for entity and cost centre, entities with their system and NetSuite subsidiary, the NetSuite mapping (accounts, departments, terms, currencies, vendors). USE WHEN: before changing the configuration, or to explain why an invoice maps the way it does. NOT FOR: invoices (talonic_ap_bills). ARGS: none. RETURNS: { config, saved, updated_at }.
talonic_ap_issues
ChatGPTThe AP worklist: every held invoice, why (each hold with its reason, finding, explanation and dollars), and the dollars at stake. USE WHEN: deciding what to dispute or fix before posting. NOT FOR: invoices ready to post (talonic_ap_bills with status=ready). ARGS: none. RETURNS: { currency, data[] { key, vendor, invoice_number, entity, document_id, filename, amount, at_stake, holds[] } }.
talonic_ap_netsuite_post
ChatGPTPost the vendor bills to the SIMULATED NetSuite sandbox: each record is answered as NetSuite's REST API answers a created record (204 with the new internal id), and the run's posting log is kept. Nothing is sent to any NetSuite account; say so when reporting the result. USE WHEN: the user asks to run the NetSuite export or a shadow posting. NOT FOR: looking at the payload (talonic_ap_netsuite_preview). ARGS: include_held (held invoices on payment hold), dry_run (answer without keeping the run), limit. RETURNS: { id, records, amount, results[] { bill_key, external_id, internal_id, status, location, payment_hold }, skipped[], log[] }.
talonic_ap_netsuite_preview
ChatGPTThe exact NetSuite vendor bill records a posting would send (REST Record API vendorBill bodies: entity, subsidiary, tranId, tranDate, dueDate, terms, currency, expense / item sublists, memo naming the source document and page), and the invoices left out with the reason. The NetSuite target is a simulated sandbox. USE WHEN: showing or checking what would be exported to NetSuite. NOT FOR: posting (talonic_ap_netsuite_post). ARGS: include_held (also send held invoices, on payment hold; duplicates are never sent). RETURNS: { adapter { mode: 'simulated_sandbox' }, records[] { bill_key, method, path, body }, skipped[], totals }.
talonic_ap_netsuite_runs
ChatGPTSimulated NetSuite posting runs: the list, or one run with its internal ids and posting log. USE WHEN: checking what an earlier export posted. NOT FOR: posting (talonic_ap_netsuite_post). ARGS: run_id (one run; omit for the list). RETURNS: { data[] } or one run { results[], skipped[], log[] }.
talonic_ap_overview
ChatGPTAP totals for the workspace: invoices ready to post and held (count and dollars), dollars at stake above contract, duplicates, missing PO, per entity with its system of record, and the last simulated NetSuite run. USE WHEN: the headline ("how much is ready to post, how much is held and why"). NOT FOR: the invoices themselves (talonic_ap_bills); the held worklist (talonic_ap_issues). ARGS: none. RETURNS: { as_of, currency, configured, gaps[], totals { bills, ready, held { at_stake, above_contract, duplicates, missing_po, vendor_unknown } }, entities[], sources[], last_run }.
talonic_ap_save_config
ChatGPTReplace the AP configuration with a complete new one (validated by the platform). Run with dry_run first. USE WHEN: setting up AP for a workspace or changing the NetSuite mapping. NOT FOR: partial edits; read talonic_ap_config, change it, and send the whole object. ARGS: config (the whole configuration object), dry_run (validate only). RETURNS: { config, saved }. A broken config returns the list of problems.
talonic_ask
ChatGPTAsk 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.
talonic_claim_agent_task
ChatGPTClaim 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.
talonic_claim_decision_task
ChatGPTClaim 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.
talonic_contracts_contract
ChatGPTRead one contract in full: terms in force (each with the document and verbatim quote it rests on), documents in fold order with what each states (unverified values carry their problem), key dates, decisions and links to the other apps. USE WHEN: checking or cleaning a contract; you need document row ids for talonic_contracts_update_document. NOT FOR: the list of contracts (talonic_contracts_register). ARGS: contract_id. RETURNS: { contract, documents[] { id, document_id, filename, role, excluded, extract }, key_dates[], links, decision, history }.
talonic_contracts_decide
ChatGPTRecord a decision on a contract: terminated, notice_sent, renewal_declined, or active (withdraws the earlier one). Recorded as made through the API key, with your note; the contract's status, end and key dates follow. USE WHEN: the user states the decision or it is confirmed by a document they point to. Never infer a termination on your own. NOT FOR: a termination letter already in the documents (it is read as a fact; check talonic_contracts_contract). ARGS: contract_id, state, note (say where the decision comes from). RETURNS: the contract, recomputed.
talonic_contracts_import
ChatGPTQueue contract documents to be read; the platform reads them in the background (one model call each) and files each under its contract. USE WHEN: filling the app. all: true queues every unread candidate (narrow with query, contract_keys, only_priced; limit for a first batch); document_ids queues exactly those. Always run all with dry_run: true first and say how many documents it will read. NOT FOR: reading a contract again after cleaning (talonic_contracts_reread). ARGS: all or document_ids; with all: query, contract_keys, only_priced, limit, dry_run; with document_ids: force (read again even if read). RETURNS: all → { dry_run, contracts, documents, queued, skipped }; document_ids → { queued, skipped }. Then poll talonic_contracts_import_status.
talonic_contracts_import_candidates
ChatGPTContract documents whose terms have not been read yet, grouped by the contract key in their filename; keys Contract Pricing already models first. USE WHEN: choosing what to read, or checking how the documents will group before importing. NOT FOR: reading them (talonic_contracts_import). ARGS: query (filename contains). RETURNS: data[] { contract_key, in_price_baseline, documents[] { document_id, filename, import } }.
talonic_contracts_import_status
ChatGPTWhere the read queue stands: counts by status (pending, running, done, failed) and the latest failures with their error. USE WHEN: after talonic_contracts_import, poll until pending and running are 0. NOT FOR: the contracts themselves (talonic_contracts_register). ARGS: none. RETURNS: { counts, failed[] { document_id, filename, error, attempts } }.
talonic_contracts_issues
ChatGPTThe cleaning worklist: contracts that look wrong and why. Codes: several_base_contracts (one key holds several contracts), printed_number_differs, several_counterparties, several_sites, ended_by_message (an email read as the termination), unread_documents, no_dates, unverified_terms. USE WHEN: after an import, to decide what to fix; again after fixing, to confirm it is clean. NOT FOR: contracts that are fine (talonic_contracts_register). ARGS: code (only contracts with this issue, optional). RETURNS: data[] { contract_id, contract_key, title, status, issues[] { code, detail, document_ids } }. document_ids are workspace document ids; match them to documents[].document_id in talonic_contracts_contract.
talonic_contracts_key_date
ChatGPTMark a key date handled (or open again), e.g. a notice deadline someone has dealt with. Handled dates leave the upcoming list and raise no alert. USE WHEN: the user confirms a date is taken care of. NOT FOR: changing the date itself (it follows the documents). ARGS: key_date_id (key_dates[].id from talonic_contracts_contract or id from talonic_contracts_upcoming), handled, note. RETURNS: { id, handled }.
talonic_contracts_merge
ChatGPTMove every document of one contract under another key (the same contract read under two keys, e.g. '1042460' and '1042460-WLV'). The emptied contract disappears. USE WHEN: two register rows are the same contract. NOT FOR: moving single documents (talonic_contracts_update_document). ARGS: contract_id (the one to empty), into_key. RETURNS: { moved, contract } — the contract under into_key, recomputed.
talonic_contracts_register
ChatGPTList the workspace's contracts: key, title, counterparty, status, start, end in force, notice deadline, document count, next open date, and what Contract Pricing and Money Found report per contract. USE WHEN: getting an overview, finding a contract by key/name, or counting by status. NOT FOR: one contract's terms and documents (talonic_contracts_contract); what needs cleaning (talonic_contracts_issues). ARGS: query (key, title or counterparty contains), status, key (exact). RETURNS: data[] { id, contract_key, title, counterparty, status, effective_date, expiry_date, notice_deadline, documents, next_date, links }.
talonic_contracts_reread
ChatGPTRead a contract's documents again (or one of them), e.g. after cleaning or when values did not verify. One model call per document; hand-set values and roles are kept. USE WHEN: a contract's terms look wrong and the documents are right. NOT FOR: documents never read (talonic_contracts_import). ARGS: contract_id, document_row_id (optional, all when omitted). RETURNS: { queued, skipped }. Then poll talonic_contracts_import_status.
talonic_contracts_set_term
ChatGPTSet one term on one document by hand, with the passage that states it copied verbatim from that document. The platform saves it only when the quote occurs in the document and prints the value. USE WHEN: a term was missed or read wrong and you have the exact passage (talonic_get_document or talonic_search to find it). NOT FOR: guessing a value; decisions (talonic_contracts_decide). ARGS: contract_id, document_row_id, field, value (ISO date for dates; fraction for escalation_pct; months for *_months), quote. RETURNS: the contract, recomputed; an error naming the problem when the quote does not verify.
talonic_contracts_upcoming
ChatGPTOpen key dates across all contracts, soonest first: notice deadlines, ends of term, renewals, price changes, terminations, dated obligations. Dates marked handled are left out. USE WHEN: what needs someone soon; preparing a renewal or notice decision. NOT FOR: one contract's dates (talonic_contracts_contract). ARGS: days (horizon, default the workspace's alert horizon, 90). RETURNS: data[] { id, contract_id, contract_key, title, kind, due_date, days_left, label, quote }.
talonic_contracts_update_document
ChatGPTFix one document of a contract: set what it is (role), leave it out of the fold (excluded), file it under another contract key (contract_key; a new key creates that contract, null returns it to its derived key), or take it off the contract (remove). USE WHEN: cleaning — a key holds several contracts (move each set to its own key, e.g. '1042460-WLV / An der Walze 12'), an email is read as a termination (exclude it), an amendment is read as a base contract (role). NOT FOR: moving all documents of a contract at once (talonic_contracts_merge). ARGS: contract_id, document_row_id, and one or more of role, excluded, contract_key; or remove: true alone. RETURNS: the contract the document ends up in, recomputed. A hand-set key and role survive re-reading.
talonic_fail_decision_task
ChatGPTReport 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.
talonic_field_values
ChatGPTRead 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.
talonic_filter
ChatGPTSTATUS: stable. Field-name resolution is server-side. Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side. USE WHEN: - The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'. - The query is value-based on extracted fields, not a free-text concept search. - You need to retrieve a sortable, paginated list filtered by field conditions. DO NOT USE WHEN: - The user wants conceptual / free-text search across content (use talonic_search). - The user is looking for a single document by id (use talonic_get_document). - The user wants extracted data from a new document (use talonic_extract). OPERATORS: - eq, neq: equality / inequality. - gt, gte, lt, lte: numeric or date comparisons. - between: requires both value and value_to. - contains: substring match on string fields. - is_empty: presence check, no value needed. Returns documents where the field is null or missing. - is_not_empty: presence check, no value needed. Returns documents where the field has a materialized value. Results reflect data within seconds of extraction completing. SCHEMA TYPING: - Numeric operators (gt, gte, lt, lte, between) only resolve correctly when the schema field is typed as number. A field typed as string that holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time. - Preventive check: call talonic_search first and inspect fieldMatches[].dataType / fields[].dataType on the field you intend to filter. If dataType !== 'number', do NOT use a numeric operator on it — either pick a different field, switch to a string-friendly operator (eq, contains), or warn the user that the schema field needs a data_type change before the filter can succeed. - Reactive fallback: if the filter response contains a warnings array, surface its message (and suggestion, if present) to the user verbatim — these explain why a query returned zero or unexpected results and typically suggest a schema-design change. Do not silently retry without flagging the warning. TIPS: - To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as field here. Fields with filterable: false have no extracted data yet. - fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering. - Both field (name) and field_id (UUID) reach the API as fieldId. Either is fine.
talonic_find_data
ChatGPTLocate 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.
talonic_get_agent_task
ChatGPTFetch 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.
talonic_get_answer
ChatGPTPoll 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 }.
talonic_get_balance
ChatGPTSTATUS: stable. Read the user's current Talonic credit balance, EUR value, 30-day burn rate, projected runway, tier, and next-tier-reset timestamp. Use this to make budget- aware decisions before kicking off large batches or re-extractions. USE WHEN: - The user asks how many credits or how much budget they have left. - You are about to run a large or expensive operation (batch extract, re-extract many documents) and want to confirm budget headroom first. - The user asks how long their balance will last at the current rate. DO NOT USE WHEN: - The user just wants the per-call cost of a single extraction (that is already on the talonic_extract response under cost). - The user wants to top up credits (route them to the dashboard; auto top-up is guarded by a separate scope). RESPONSE SHAPE: - balance_credits: current credit balance. - balance_eur: current balance in EUR (rounded to two decimals). - burn_rate_30d_credits: total credits consumed in the trailing 30 days. - projected_runway_days: days of runway at the current 30-day average burn. -1 indicates no consumption in the trailing window (cannot compute runway). - tier: API tier of the workspace (free, pro, enterprise, etc.). - tier_resets_at: ISO 8601 timestamp of the next monthly tier reset.
talonic_get_document
ChatGPTSTATUS: stable. Fetch full metadata for a single document already in the user's Talonic workspace. Returns id, filename, page count, detected document type, language, processing log, and link URLs (self, extractions, dashboard). USE WHEN: - You need details about a specific document the user already extracted or uploaded. - You have a document_id from a previous extract or search call and want more context. - You called talonic_request_upload and need to poll until the user has uploaded the file. - The user asks 'tell me about document X' or similar. DO NOT USE WHEN: - The user wants the document's full text content (use talonic_to_markdown for OCR markdown). - The user wants extracted structured data (use talonic_extract with a schema, or fetch the extraction by id). - The user has a file but no document_id yet (call talonic_extract first to ingest the document). STATUS VALUES on the response status field: - pending_upload: document slot reserved via talonic_request_upload, file not yet received. Keep polling (~5 s interval). Token expires after 15 min — if status stays 'pending_upload' past the expires_at returned by talonic_request_upload, the user did not upload in time. - queued / extracting: file received, OCR and exhaustive extraction in progress. Keep polling. - completed: extraction is done. This is the state to wait for before calling talonic_extract with a schema or schema_id — the schema-specific LLM pass runs off the cached OCR'd text. - uploaded: file received but the extraction queue could not be enqueued (rare, e.g. Redis unavailable). The talonic_extract endpoint will trigger processing inline if called. - error / ocr_failed / extraction_failed: terminal failures; processing_log carries the reason.
talonic_get_field
ChatGPTGet 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.
talonic_get_pricing
ChatGPTRead 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 }.
talonic_get_run
ChatGPTPoll 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 }.
talonic_get_run_results
ChatGPTRead 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 }.
talonic_get_spec
ChatGPTGet 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[].
talonic_get_usage
ChatGPTRead 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.
talonic_heartbeat_agent_task
ChatGPTExtend 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.
talonic_heartbeat_decision_task
ChatGPTExtend 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.
talonic_list_agent_tasks
ChatGPTList 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.
talonic_list_decision_tasks
ChatGPTList 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.
talonic_list_fields
ChatGPTList 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.
talonic_list_schemas
ChatGPTSTATUS: stable. List all saved schemas in the user's Talonic workspace. Returns a COMPACT SUMMARY of each schema: id (UUID), short_id (SCH-XXXXXXXX), name, description, version, and field_count. Either id form is accepted by talonic_extract's schema_id parameter, so you can extract with a saved schema straight from this list. The full JSON Schema definition for each field is intentionally NOT included here — for many schemas that payload is large and gets truncated by some clients. To inspect a schema's full field definitions, read the talonic://schemas resource. USE WHEN: - The user asks what schemas they have, or asks to see existing schemas. - You want to discover existing schemas before designing a new one. - Before recommending the user create a schema, check if one already covers the use case. - The user asks to extract from a known document type and you want to find a matching schema. DO NOT USE WHEN: - The user just wants to extract data from a document and provides an inline schema (call talonic_extract directly). TIP: Pair this with talonic_extract by passing the chosen schema's id as schema_id.
talonic_list_specs
ChatGPTList 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 } }.
talonic_master_records_changes
ChatGPTMaster data changes from the source systems' change logs, each checked against the evidence documents: a bank account change matches when a document for the party names the new account, contradicts when documents name another, no_document otherwise; flagged bank changes carry the party's open payables across every source as exposure. Read live; nothing is stored. USE WHEN: "which bank detail changes have no document behind them", vendor bank fraud checks, terms changes. NOT FOR: the golden records (talonic_master_records_overview). ARGS: domain, flagged (only the changes that need attention). RETURNS: { domain, stats { changes, bank_changes, bank_matched, bank_contradicted, bank_no_document, terms_no_document, flagged, exposure, evidence_documents }, evidence_run, changes[] { source, id, field, old_value, new_value, changed_at, changed_by, golden_key, golden_name, verdict, flagged, evidence[], exposure, elsewhere[], explanation } }.
talonic_master_records_config
ChatGPTRead the Master Records configuration: per domain (vendors, customers, materials) the source systems (label, SQL connection, the read-only SELECT aliasing columns to the canonical fields; order is survivorship priority), the match thresholds, and the optional change logs, open items and evidence Spec. USE WHEN: before changing the configuration, or to explain which systems feed a domain. NOT FOR: the golden records (talonic_master_records_overview). ARGS: none. RETURNS: { domains { vendors|customers|materials { sources[], auto_threshold?, review_threshold?, changes[]?, open_items[]?, evidence? } } }.
talonic_master_records_crosswalk
ChatGPTThe crosswalk: every source row (source, source id) mapped to its golden record key and name and the record's status, single-source rows included. USE WHEN: looking up which golden record a system's id belongs to, or handing the mapping to another system. NOT FOR: the merge reasons (talonic_master_records_get_record). ARGS: domain. RETURNS: { domain, rows[] { golden_key, golden_name, source, source_id, status } }.
talonic_master_records_get_record
ChatGPTOne golden record: each member row with its source and values, the golden value per field with the sources it came from, the fields where sources disagree (bank account and tax id are bad), the field-by-field reasons the rows were linked, status, score and any decision. USE WHEN: explaining why rows were merged, which system a value came from, or before accepting or splitting a record. NOT FOR: listing records (talonic_master_records_overview). ARGS: domain, key (from talonic_master_records_overview or talonic_master_records_crosswalk). RETURNS: { key, domain, name, members[] { source, id, values }, golden { <field> { value, from[] } }, conflicts[] { field, severity, values[] }, reasons[] { field, outcome, weight }, score, status, run_id, decision }.
talonic_master_records_overview
ChatGPTA domain's latest run (stats per source, records, merged, to review, conflicts) and its golden records that join two or more source rows, review and bank / tax id conflicts first, each with status, match score, member sources and conflicting fields. USE WHEN: the headline ("how many duplicates across the ERPs, how many need review") or finding a record by name or source id. NOT FOR: one record's fields and reasons (talonic_master_records_get_record); single-source rows (talonic_master_records_crosswalk). ARGS: domain, status review|auto|accepted|split|conflict|all (default all), query (name or source id contains), limit (default 100), offset. RETURNS: { domain, run { id, status, stats, started_at, finished_at }, total, records[] { key, name, member_count, status, score, conflict_level, sources[] { source, id }, conflict_fields[] } }.
talonic_master_records_save_config
ChatGPTReplace the Master Records configuration with a complete new one (validated by the platform: every SQL is checked read-only against its connection). Run with dry_run first. Saving needs an owner. USE WHEN: setting up Master Records for a workspace, or adding a source system or change log. NOT FOR: partial edits; read talonic_master_records_config, change it, and send the whole object. ARGS: config (the whole configuration object), dry_run (validate only). RETURNS: { config, saved }. A broken config returns the list of problems.
talonic_parties_confirm
ChatGPTConfirm suggested roles in bulk: by default only high-confidence suggestions (a verified quote the contract register agrees with), optionally only of named contracts or roles. Confirming says a person checked them; it is the user's decision, so only call this when the user asked. Run with dry_run first and say how many it would confirm. USE WHEN: the user asks to accept the suggestions (all, or of some contracts / roles). A read only makes suggestions and never overwrites a person's decision (a confirmed role stays, a rejected one never comes back). Confirming, rejecting and merging are a person's decisions: only do them when the user asked. NOT FOR: rejecting or fixing one role (talonic_parties_set_role). ARGS: contract_ids[] (omit for all), roles[] (e.g. ['partner']), min_confidence high|medium|low (default high), limit (1-5000, default 500), dry_run. RETURNS: { dry_run, confirmed, rows[] { id, contract_id, party_id, role, confidence } } (rows: the first 100).
talonic_parties_contract
ChatGPTOne contract's parties on a day: the computed view (partner, manager, tenant, previous and new owner, effective partner, addressee with its postal address lines, contacts, state), every role row with its party, state (suggested|confirmed|rejected), confidence and evidence (document quotes, reference table rows, a person's word), the issues, the cost unit (documents vs. contract register) and the read state. USE WHEN: checking or fixing a flagged contract; you need role ids (roles[].id) for talonic_parties_set_role, or to answer who the partner is and where a letter goes. Roles: partner (the contract partner), manager (Verwalter: acts for a company or an owners' association and is written to on its behalf; represents_id names the role it acts for), tenant (with enters_contract: true the tenant is the temporary partner for the lease period valid_from..valid_to), previous_owner / new_owner (an owner change: the new owner holds from the transfer date valid_from), contact, invoice_recipient. The effective partner (the tenant entering the contract during its lease, else the partner) and the addressee (the effective partner's Verwalter when it has one, else the effective partner) are computed by the platform from the roles in force on the day; never set them yourself, fix the roles. NOT FOR: the list of contracts (talonic_parties_contracts); one party across contracts (talonic_parties_party). ARGS: contract_id, on (YYYY-MM-DD; default today: the roles in force on that day). RETURNS: { contract { id, contract_key, title, counterparty, status }, on, view { partner, manager, tenant, previous_owner, new_owner, effective_partner, addressee { ...party, role_id, role, state, valid_from, valid_to, address_lines[] }, contacts[], state }, roles[] { id, party_id, role, represents_id, valid_from, valid_to, enters_contract, state, confidence, evidence[], origin, decided_by, decided_at, note, party }, issues[], cost_unit { documents, quote, register[] }, reference_names[], read { status, read_at, error, notes, read_with } | null }.
talonic_parties_group_companies
ChatGPTRead the workspace's own companies (the group: lead company, subsidiaries, sisters), or replace them all with companies. The read uses them to tell our side from the contract partner. Replacing deletes every company not in the new list: read first, change, send the whole list, and only when the user asked. USE WHEN: a read takes one of our own companies for the partner, or setting up the workspace. NOT FOR: contract partners (talonic_parties_party). ARGS: none to read; companies[] { name, parent? (another name in the list), relation? subsidiary|sister|parent } to replace. RETURNS: { data[] { id, name, parent_id, relation } } (after a replace: the stored list).
talonic_parties_issues
ChatGPTThe parties worklist: per contract what looks wrong today (no partner, several partners, the reference table names another partner, person-or-company unknown, no postal address, a Verwalter for a party no longer on the contract, a tenant entering the contract without a lease period, an owner change without a transfer date, cost unit disagreeing or missing, not read, read failed), plus parties that look like duplicates (same name, and postcode when both have one). USE WHEN: after talonic_parties_read, deciding what to fix; open each flagged contract with talonic_parties_contract. Duplicates are merge candidates: never merged on their own (talonic_parties_merge, only when the user asked). NOT FOR: the headline counts (talonic_parties_status); all contracts (talonic_parties_contracts). ARGS: code (only this issue; one of no_partner, several_partners, reference_disagrees, kind_unknown, address_missing, manager_without_party, tenant_without_period, owner_change_open, cost_unit_disagrees, cost_unit_missing, not_read, read_failed, possible_duplicate). RETURNS: { contracts[] { contract_id, contract_key, title, issues[] { code, detail, role_ids[], party_ids[] } }, duplicates[] { name_key, party_ids[], names[] } }.
talonic_parties_members
ChatGPTAdd a contact person to a company or an owners' association (with their function), or remove a contact link. A contact is always a person; the company is a company or an owners' association. Adding the same person again updates the function. USE WHEN: the user names the person to write to at a company (e.g. the WEG's Verwalter contact), or a contact left. NOT FOR: a contact role on one contract (talonic_parties_set_role with role contact). ARGS: add: party_id (the company), person_id, function (e.g. 'Geschäftsführer'); remove: member_id (members[].id from talonic_parties_party) alone. RETURNS: add: the link { id, company_party_id, person_party_id, function }; remove: { ok: true }.
talonic_parties_merge
ChatGPTMerge one party into another: every role and contact link moves to the survivor (into); a role the survivor already holds on the same contract keeps the survivor's row and takes the merged one's evidence. The merged party stays only as a pointer to the survivor. Cannot be undone; a person's decision, so only when the user asked. Run with dry_run first. USE WHEN: talonic_parties_issues lists duplicates (same name and postcode) and the user confirms they are the same party. NOT FOR: two different parties with similar names; moving one role to another party (talonic_parties_set_role with role_id and party_id). ARGS: party_id (the one that goes), into (the survivor), dry_run. RETURNS: { dry_run, moves, combined, party } (party: the survivor, after a real merge).
talonic_parties_party
ChatGPTRead, change or create one party. With party_id alone: the party with its roles on every contract, its contacts (members), the companies it is a contact of and the documents it appears in (with quotes). With party_id and fields: changes those fields (the rest stay). Without party_id: creates a party; display_name is required (kind and salutation are inferred from it when not given). USE WHEN: checking a party; fixing its name, kind (person or company decides a letter's wording), salutation or postal address (issues kind_unknown, address_missing); creating a party the documents miss before adding it to a contract with talonic_parties_set_role. Search first (talonic_parties_search) so you do not create a duplicate. NOT FOR: its role on a contract (talonic_parties_set_role); combining duplicates (talonic_parties_merge). ARGS: party_id (omit to create); fields kind person|company|owners_association|unknown, display_name, salutation herr|frau|eheleute|firma|weg, title, first_name, last_name, company_name, legal_form, street, postcode, town, country, email, phone, preferred_channel post|email, external_refs { name: value } (null clears a text field). RETURNS: read { party, merged_into, roles[] { ...role, contract }, members[] { id, function, party }, member_of[], documents[] { document_id, filename, quotes[] } }; change or create: the party.
talonic_parties_set_role
ChatGPTAdd a role to a contract, or change one role row. With contract_id, party_id and role: adds the party in that role (confirmed unless state says suggested; a party already holding that role on the contract has that row updated). With role_id: changes that row: confirm or reject it (state), move it to another role or party, set the period, the Verwalter link or enters_contract. Any change by a person is a decision: an edited suggestion becomes confirmed unless state says otherwise. USE WHEN: fixing a contract's parties after reading talonic_parties_contract: a partner missing (no_partner), two partners at once (reject the wrong one, or give the old one valid_to), a Verwalter for the right party (represents_id), a tenant entering the contract (enters_contract with valid_from / valid_to), an owner change (previous_owner, new_owner with valid_from = transfer date). Roles: partner (the contract partner), manager (Verwalter: acts for a company or an owners' association and is written to on its behalf; represents_id names the role it acts for), tenant (with enters_contract: true the tenant is the temporary partner for the lease period valid_from..valid_to), previous_owner / new_owner (an owner change: the new owner holds from the transfer date valid_from), contact, invoice_recipient. The effective partner (the tenant entering the contract during its lease, else the partner) and the addressee (the effective partner's Verwalter when it has one, else the effective partner) are computed by the platform from the roles in force on the day; never set them yourself, fix the roles. A read only makes suggestions and never overwrites a person's decision (a confirmed role stays, a rejected one never comes back). Confirming, rejecting and merging are a person's decisions: only do them when the user asked. NOT FOR: confirming many suggestions at once (talonic_parties_confirm); the party's own details (talonic_parties_party). ARGS: add: contract_id, party_id, role; change: role_id (roles[].id from talonic_parties_contract) and optional party_id, role. Both: state suggested|confirmed|rejected, represents_id (another role id on the same contract; null clears), valid_from, valid_to (YYYY-MM-DD; null clears), enters_contract (tenant only), note (say where the decision comes from). RETURNS: the role row { id, contract_id, party_id, role, represents_id, valid_from, valid_to, enters_contract, state, confidence, evidence[], origin, decided_by, decided_at, note }.
talonic_parties_status
ChatGPTContract Party Management at a glance: how many contracts, how many have confirmed parties, only suggestions, or no partner; active parties; open suggestions; and the parties-read queue. USE WHEN: starting any parties work, or to report where things stand. The loop: talonic_parties_status → talonic_parties_read (dry_run first, then with wait_seconds) → talonic_parties_issues → talonic_parties_contract per flagged contract → talonic_parties_set_role / talonic_parties_confirm → talonic_parties_merge duplicates → talonic_parties_issues again. NOT FOR: what to fix (talonic_parties_issues); one contract (talonic_parties_contract). ARGS: none. RETURNS: { contracts, contracts_confirmed, contracts_suggested, contracts_without_partner, parties, suggestions, reads { counts { pending, running, done, failed }, unread, failed } }.
talonic_read_decision_package
ChatGPTRead 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.
talonic_release_decision_task
ChatGPTRelease 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.
talonic_request_upload
ChatGPTSTATUS: stable. Request a file upload link for the user. Use this when the user wants to extract a file but you cannot deliver it directly (e.g., the file is too large for tool-call arguments, or you're running in a sandboxed environment like Claude.ai). Returns an upload URL the user can open in their browser to drop the file, plus a document_id to track the upload. After showing the URL to the user, poll with talonic_get_document until status is 'completed' (the file has been uploaded, OCR'd, and is ready for schema-specific extraction). Then call talonic_extract with the document_id and a schema or schema_id. IMPORTANT: a user message like 'uploaded', 'done', or 'I dropped it' only confirms the browser-side upload finished. It is NOT a signal that server-side processing is complete. The document still needs OCR and exhaustive extraction (typically 10-30 s after the browser upload). You MUST poll talonic_get_document yourself until status is 'completed' regardless of what the user says. Calling talonic_extract before status is 'completed' may return errors. USE WHEN: - The user has a file to extract but you cannot send it via tool-call arguments (e.g., file is larger than ~32KB, or the environment blocks outbound data). - You are running in a hosted/sandboxed environment (Claude.ai, ChatGPT) where file_data cannot be used reliably. - The user explicitly asks for an upload link. DO NOT USE WHEN: - You can deliver the file directly via file_data (local-stdio installs with small files). - The file is already accessible via a public URL (use file_url on talonic_extract instead). - The document is already in the workspace (use document_id on talonic_extract instead).
talonic_run_spec
ChatGPTRun 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.
talonic_save_schema
ChatGPTSTATUS: stable. Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id. USE WHEN: - The user asks to save a schema, store a template, or reuse the schema across docs. - You have iterated on a schema with the user and they confirmed it should be saved. - The user wants to standardise extraction across many documents of the same type. DO NOT USE WHEN: - The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline). - The user has not confirmed the schema design (avoid creating clutter in their workspace). DEFINITION FORMATS: - JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } } - Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema. TIP: After saving, call talonic_extract with schema_id set to the returned id (UUID or SCH- short id) for consistent results.
talonic_search
ChatGPTSTATUS: stable. Search the user's Talonic workspace for documents, fields, sources, or schemas matching a query. Returns ranked results across all entity types in one call. USE WHEN: - The user wants to find documents but does not know the exact filename or id. - The query is conceptual ('contracts mentioning indemnification', 'Acme invoices'). - You need to narrow a large workspace before calling talonic_extract or talonic_filter. - The user asks 'do I have any docs about X' or 'find anything related to X'. DO NOT USE WHEN: - The user has a specific document_id (use talonic_get_document instead). - The user wants to apply structured field-value filters like 'amount > 1000' (use talonic_filter). - The user wants to extract data from a brand-new document (use talonic_extract). TIP: The result includes documents, fieldMatches, sources, schemas, and fields. Both fields[] and fieldMatches[] include a filterable boolean. Only entries with filterable: true can be used with talonic_filter. Fields with filterable: false exist in a schema but have no extracted data yet. Pick the entity type the user actually needs.
talonic_submissions_completeness
ChatGPTOne submission against a target structure: for every metric the client's format knows, how many facts the submission has and which fields they fill, plus metrics found that are not in the format. USE WHEN: judging whether a submission carries what a quote needs, or explaining what is missing. NOT FOR: the facts themselves (talonic_submissions_export). ARGS: document_id, spec_id. RETURNS: { metrics[] { metric, in_format, facts, fields[] } }.
talonic_submissions_export
ChatGPTFacts in the client's long format: a header (the structure's fields, then Metric, Figure, Document, Source) and one row per figure; Source is the cell the figure came from. Large: prefer one document. USE WHEN: handing facts to the client or another system, or answering a question about figures. NOT FOR: the inbox (talonic_submissions_list). ARGS: spec_id, document_id (optional; all submissions when omitted). RETURNS: { header[], rows[][] }.
talonic_submissions_issues
ChatGPTThe worklist: what needs a person, naming the submissions concerned. Kinds: not_captured, capture_failed, not_mapped, check_failed (with count), labels_to_review (with count), missing_metric (format metrics with no facts in a submission). USE WHEN: deciding what to do next; after talonic_submissions_process to see what is left. NOT FOR: the full list (talonic_submissions_list). ARGS: spec_id (optional; mapping-related kinds need it). RETURNS: [{ kind, document_id, filename, detail }].
talonic_submissions_list
ChatGPTThe inbox: every submission workbook of the workspace with its cedent, status (not_captured, captured, mapped, failed), captured values, facts and metrics under a target structure, and failed / warned checks. USE WHEN: the headline ("which submissions are in, which are mapped, which have problems") or finding a submission by file name. NOT FOR: what to fix (talonic_submissions_issues); the facts (talonic_submissions_export). ARGS: spec_id (optional), q (file name contains), limit (default 100, max 500), offset. RETURNS: { total, submissions[] { document_id, filename, cedent, status, tables, values, facts, metrics, checks_failed, checks_warned, embedded_files, captured_at } }.
talonic_submissions_specs
ChatGPTList the workspace's target structures: the client formats submissions are mapped into, with field count and how many label mappings still await review. USE WHEN: before any other submissions tool, to pick the spec_id. NOT FOR: the submissions themselves (talonic_submissions_list). ARGS: none. RETURNS: [{ id, name, updated_at, field_count, labels_to_review }].
talonic_submit_agent_task
ChatGPTSubmit 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.
talonic_submit_decision_task
ChatGPTSubmit 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.
talonic_to_markdown
ChatGPTSTATUS: stable. Get the OCR-converted markdown for a document. Accepts an existing document_id, raw file bytes (base64), a local file path, or a URL. When given a raw file, the tool ingests it via extract first and then returns the markdown. USE WHEN: - The user wants the full text content of a document for summarisation, translation, or analysis. - A previous tool call returned a document_id and you want to inspect its content. - The user asks 'what does the document say' or 'summarise this PDF' (you call this then summarise). - The user has a raw PDF / scan / image and wants markdown directly without designing a schema first. DO NOT USE WHEN: - The user wants specific structured fields (use talonic_extract with a schema). INPUTS (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path): - document_id: id of an already-ingested document. Cheapest path, one API call. - file_data + filename: base64-encoded file bytes plus the original filename (with extension). RECOMMENDED for local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). WARNING for hosted-MCP via Claude.ai connectors: Claude.ai imposes a hard size limit on tool-call arguments (effectively under ~1KB), so file_data CANNOT carry a real PDF through Claude.ai's pipeline. The bytes get truncated before reaching the MCP server. For files larger than a trivial test, use file_url or document_id instead when running through Claude.ai. Local stdio installs do NOT have this limit. - file_path: local path to a document file. Only works if the MCP server has read access to that path; in sandboxed chat clients use file_data instead. - file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. Best path for Claude.ai users dealing with files larger than the parameter cap.
