Skip to main content

Browser-Handoff Upload

Create an upload session with POST /v1/documents/upload-session and hand the browser URL to a user. The short-lived token authenticates the file upload.

The browser-handoff pair uploads a file that lives on the user's machine, not the caller's. POST /v1/documents/upload-session creates a pending document row plus a short-lived token and returns a browser upload_url; the user opens that URL, picks the file, and the browser posts it to POST /v1/upload/{token}. The hosted MCP connector uses this flow: the agent never touches the file bytes, it only mints the session and polls the document afterwards.

Auth is asymmetric across the pair, and that asymmetry is the design. The session route requires an OAuth 2.1 bearer token from the connector OAuth flow and rejects tlnc_ API keys with 401. The upload route is public: it reads no Authorization header at all, because the single-use, short-lived token in the path is the credential. The token expires after 15 minutes by default, and it is claimed atomically, so a second post with the same token gets 404 even when it races the first.

POST/v1/documents/upload-session

Body parameters

filename*stringFilename of the file the user will upload (max 512 characters).

Response (session)

{
  "document_id": "f0e1d2c3-b4a5-9687-8765-432109876543",
  "upload_url": "https://app.talonic.com/u/1f2e3d4c-5b6a-7980-abcd-ef0123456789",
  "expires_at": "2026-07-31T12:15:00.000Z"
}
POST/v1/upload/{token}

Upload (what the browser page does)

Response (upload)

{
  "document_id": "f0e1d2c3-b4a5-9687-8765-432109876543",
  "status": "queued",
  "filename": "invoice-2026-04.pdf"
}
Do not send a tlnc_ API key to the session route; it returns 401 by design. For server-side uploads where the caller holds the file bytes, use the standard ingestion routes such as POST /v1/extract or a source's document upload endpoint instead.

Errors

Error responses

400bad_requestMissing filename on the session route, or no file in the multipart body on the upload route.
401unauthorizedSession route only: missing or invalid OAuth bearer token, or a tlnc_ API key was used.
404not_foundUpload route only: token not found, expired, or already used.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

On a successful upload the document is stored and extraction is enqueued, so the returned status is normally queued. When the queue is temporarily unavailable the document stays at uploaded, and a later POST /v1/extract call with the document_id still processes it inline. The session's pending document is created for extraction only; once the file arrives, drive it with POST /v1/extract like any other document.

Related

List Documents
Get Document
Extract Data