talonic_request_upload

Request a one-time upload link for a file the agent cannot deliver directly. Returns a pre-allocated document_id, a browser-openable upload_url the user drops the file into, and an expires_at timestamp.

`talonic_request_upload` exists to route around the ~32 KB tool-call argument cap in hosted-connector environments like Claude.ai's web UI. Above that ceiling, file_data on talonic_extract is silently truncated and the extraction returns null fields. The browser-handoff flow sidesteps the cap entirely: the user opens the upload URL in a separate tab, drops the file, and the agent then references the resulting document by ID.

Local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork) do not have this cap and should keep using file_data for small-to-medium files. This tool is for the hosted connector path or any sandboxed environment where you can't reliably stream the file through the tool call.

When to use

• The user has a file to extract and you are running in a hosted-connector environment (Claude.ai, ChatGPT) where file_data is not reliable.
• The file is larger than ~32 KB (typical for real invoices, contracts, COIs).
• The user explicitly asks for an upload link.

When not to use

• 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.

{
  "filename": "invoice-2026-001.pdf"
}

{
  "document_id": "doc_8f3a2b9c-1d4e-5f6a-7b8c-9d0e1f2a3b4c",
  "upload_url": "https://app.talonic.com/upload/u_3f9d2a1c8b7e6f5d4c3b2a1f0e9d8c7b",
  "expires_at": "2026-05-28T20:35:00.000Z"
}

End-to-end workflow

1. Call talonic_request_upload with the filename. Capture document_id, upload_url, and expires_at from the response.
2. Show the upload_url to the user and ask them to open it in a new browser tab and drop the file.
3. Poll talonic_get_document with the document_id until status is completed. Do not skip this step — a user confirmation like "uploaded" only signals that the browser-side upload finished, not that server-side OCR and processing are done.
4. Once status === "completed", call talonic_extract with the document_id and a schema or schema_id to pull out structured fields.

// 1. Agent requests an upload link.
// talonic_request_upload({ filename: "rental-agreement.pdf" })
{
  "document_id": "doc_1a2b3c4d-...",
  "upload_url": "https://app.talonic.com/upload/u_abc123...",
  "expires_at": "2026-05-28T20:35:00.000Z"
}

// 2. Agent: "Open this link in a new tab and drop your file:
//            https://app.talonic.com/upload/u_abc123...
//            I'll let you know once Talonic is done processing."

// 3. After user drops the file, agent polls:
// talonic_get_document({ document_id: "doc_1a2b3c4d-..." })
// → status: "processing"  → wait ~10s, poll again
// → status: "completed"   → ready to extract

// 4. Agent extracts:
// talonic_extract({
//   document_id: "doc_1a2b3c4d-...",
//   schema_id: "SCH-RENTAL01"
// })
// → structured JSON with per-field confidence scores

The pre-allocated document_id is a real Talonic document from the moment the upload link is minted, but it stays in pending status until the user actually uploads. If the user closes the tab or the link expires (expires_at) without uploading, the document remains in pending and can be cleaned up via the dashboard. Re-issuing a fresh upload link for the same file is safe: the new link creates a new document_id with no link to the abandoned one.

Agents should treat the upload_url as user-only information and never attempt to PUT to it themselves from the sandbox. Most sandboxed environments (Claude.ai's web tools, ChatGPT's Code Interpreter) cannot reach arbitrary S3-like endpoints, and even when they can, asking the user to open the link in their own browser preserves the user-agent boundary and avoids surprising the user with a backend upload they did not consent to.