---
title: "Create a browser-handoff upload session"
method: POST
path: "/v1/documents/upload-session"
tags: ["Documents"]
---

# Create a browser-handoff upload session

`POST /v1/documents/upload-session`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/documents/upload-session`
- Auth: HTTP bearer

Creates a pending document row plus a short-lived upload token and
returns a browser `upload_url` for it. This is the first half of the
browser-handoff upload pair used by the hosted MCP connector: an
agent creates the session, the user opens `upload_url` in a browser
and picks the file, and the browser posts it to
`POST /v1/upload/{token}`.

**Auth is asymmetric across the pair.** This route requires an
OAuth 2.1 bearer token (the connector OAuth session) and REJECTS
`tlnc_` API keys with `401`. The upload route is unauthenticated
because the short-lived token IS the credential. The token expires
after 15 minutes by default and is single-use.

The created document is targeted at extraction only
(`ingestion_target: extract`): once uploaded, call `POST /v1/extract`
with the returned `document_id`.

## Request body

- object
  - `filename` string, required: Filename of the file the user will upload.

## Response `201`

Upload session created.

- object
  - `document_id` string, uuid, required: Pending document row awaiting the upload.
  - `upload_url` string, required: Browser URL the user opens to pick and upload the file.
  - `expires_at` string, date-time, required: Token expiry (15 minutes from creation by default).

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid OAuth bearer token, or a `tlnc_` API key was used (not accepted on this route).
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)