Upload

Docs index

Direct-to-storage upload, and why bytes never reach the application server.

Note Before you start. Signing in creates your workspace, and uploading and compiling your own sources open for it once its owner accepts the processing terms. Your workspace shows whether it is open. Once it is open, the Developer plan can be bought online. Team and Enterprise are arranged with us rather than enabled by a plan purchase. Everything on this page is the contract the capability endpoint serves to a signed-in workspace.

Why bytes never reach our server

Uploads are direct. The capability endpoint returns a short-lived URL to object storage; you PUT the bytes there. The application server sees the request for permission and the receipt afterwards, and never the document.

Requesting a capability and listing documents

Note requestedBytes is the field the per-source byte ceiling acts on. Above 5 MB the answer is 413 SOURCE_EXCEEDS_PROCESSING_CEILING, carrying maxBytes, maxPages and a sentence you can show a person — before any byte is stored, because admitting the file would only move the refusal somewhere you cannot see it. A free evaluation has its own lower bound and answers TRIAL_FILE_TOO_LARGE with its own maxBytes.

POST/uploads/capabilityScope documents:intake

Returns a short-lived browser/agent-direct R2 PUT URL only when this workspace is approved for source processing. A closed workspace receives 403 CUSTOMER_DATA_NOT_ENABLED_FOR_WORKSPACE before any URL or compute reservation is issued. Document bytes never pass through the application server. `requestedBytes` is checked against the deployment's per-source ceiling here, before any byte is stored: above it the answer is 413 SOURCE_EXCEEDS_PROCESSING_CEILING carrying `maxBytes`, `maxPages` and a sentence you can show a customer. Send `x-tavonel-source-idempotency-key` (a sha256 hex digest of the source event) to make the document id deterministic, so a retried intake converges on one document rather than two.

curl -sS -X POST https://tavonel.com/api/v1/uploads/capability \
  -H "Authorization: Bearer $TAVONEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "originalFilename": "<originalFilename>", "declaredMimeType": "application/pdf", "requestedBytes": 1, "estimatedPages": 1 }'

import os
import requests

body = {
    "originalFilename": "<originalFilename>",
    "declaredMimeType": "application/pdf",
    "requestedBytes": 1,
    "estimatedPages": 1
}

response = requests.request(
    "POST",
    "https://tavonel.com/api/v1/uploads/capability",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    json=body,
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/uploads/capability", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ "originalFilename": "<originalFilename>", "declaredMimeType": "application/pdf", "requestedBytes": 1, "estimatedPages": 1 }),
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Request body

{
  "originalFilename": "<originalFilename>",
  "declaredMimeType": "application/pdf",
  "requestedBytes": 1,
  "estimatedPages": 1
}

Status	Response
`200`	A qualified direct upload capability and the immutable document id the bytes will be registered under. PUT the bytes to `uploadUrl` with content-type `declaredMimeType` and content-length `contentLength`, within `expiresInSeconds`; the URL is the credential and it is short-lived. Then confirm with `documentId`.
`400`	UNQUALIFIED_INPUT — A required field was missing or was not of the declared type. UNQUALIFIED_MIME — The declared MIME type is not in the capability manifest. FILENAME_MIME_MISMATCH — The extension and the declared MIME type disagree. INVALID_FILENAME — Same refusal from the intake validator. SOURCE_IDEMPOTENCY_KEY_INVALID — `x-tavonel-source-idempotency-key` was present and was not 64 hex characters.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns. API_KEY_INVALID — The bearer token was well-formed but did not match a stored key. API_KEY_EXPIRED — The key matched and its expiry has passed. API_KEY_REVOKED — The key matched and was revoked. A rotation revokes the key it replaces.
`402`	STUDIO_SUBSCRIPTION_REQUIRED — The operation needs the higher plan tier — activation, rollback and retrieval-index rebuild are the three. TRIAL_ARCHIVE_NOT_INCLUDED — ZIP upload is not included in the free evaluation. TRIAL_FILE_LIMIT_EXCEEDED — The free evaluation's file count is spent. GPU_CREDITS_REQUIRED — The workspace has no processing balance left to reserve against. TRIAL_PAGE_LIMIT_EXCEEDED — The free evaluation's page allowance is spent. TRIAL_NOT_ACTIVE — No free evaluation is active for this workspace. TRIAL_DISABLED — Free evaluation is closed today.
`403`	API_SCOPE_REQUIRED — The key authenticated and does not carry the scope this operation requires. The request was refused rather than answered with less. CUSTOMER_DATA_NOT_ENABLED_FOR_WORKSPACE — This workspace has no current approval to process its sources.
`409`	INTAKE_IDEMPOTENCY_CONFLICT — The same source idempotency key was already used for different bytes. COMPUTE_IDEMPOTENCY_CONFLICT — The processing reservation ledger already holds a different reservation under this request's idempotency key. SOURCE_DELETED — The uploaded source has a deletion tombstone, so its bytes cannot be admitted or served again.
`413`	SOURCE_EXCEEDS_PROCESSING_CEILING — `requestedBytes` is above what every processor in the chain can read. The body carries `maxBytes`, `maxPages` and a `limit` sentence. This is the refusal the 5 MB per-source ceiling produces. TRIAL_FILE_TOO_LARGE — Above the free-evaluation per-file bound, which is lower than the deployment ceiling.
`415`	METADATA_ONLY_ENDPOINT — Document bytes were POSTed to a route that accepts only metadata. Bytes go direct to storage, never through the application server.
`429`	API_RATE_LIMITED — The key has used its per-minute allowance for this scope. The window is a fixed clock minute per key and scope; the allowances are on /docs/billing-and-limits. INTAKE_RATE_LIMITED — Too many upload capabilities were requested in the window. INTAKE_DAILY_QUOTA_EXCEEDED — The workspace's daily intake quota is spent. TRIAL_CAPACITY_REACHED — The deployment's concurrent free evaluations are full.
`503`	SIGNER_NOT_CONFIGURED — The upload URL signer is not configured, so no capability can be issued. INTAKE_DISABLED — Intake is closed today. API_RATE_LIMIT_UNAVAILABLE — The allowance could not be read, so the request was refused rather than run unbounded.

GET/documentsScope documents:read

The workspace's immutable document inventory with each document's processing state and version key. Uploading the same file twice produces two documents that share one content digest; nothing merges them. This operation takes no paging parameters — the inventory is returned whole.

curl -sS -X GET https://tavonel.com/api/v1/documents \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/documents",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/documents", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	{ code: OK, workspaceId, documents }. A document whose source could not be resolved is present with its refusal rather than omitted.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns. API_KEY_INVALID — The bearer token was well-formed but did not match a stored key.
`403`	API_SCOPE_REQUIRED — The key authenticated and does not carry the scope this operation requires. The request was refused rather than answered with less. PILOT_ACCESS_REQUIRED — The credential is valid and the workspace it names is not admitted to TAVONEL. CONNECTOR_SOURCE_ACCESS_DENIED — The provider refused the stored credential. AUTHORIZATION_CHANGED_RETRY — The caller's authorization changed while the request was in flight, so the request was abandoned rather than finished under a permission that may no longer hold.
`429`	API_RATE_LIMITED — The key has used its per-minute allowance for this scope. The window is a fixed clock minute per key and scope; the allowances are on /docs/billing-and-limits.
`503`	CONNECTOR_SOURCE_ACCESS_UNAVAILABLE — The provider could not be reached. READ_FAILED — A backing store could not be read. QUARANTINE_LIST_UNAVAILABLE — The listing of sources that were refused or are not yet prepared could not be read. No inventory is returned rather than one that silently leaves those sources out. API_RATE_LIMIT_UNAVAILABLE — The allowance could not be read, so the request was refused rather than run unbounded.

The PUT itself

The capability response carries uploadUrl and expiresInSeconds, beside the declaredMimeType and contentLength the URL is signed for. PUT the bytes to uploadUrl with content-type set to declaredMimeType and content-length equal to contentLength: the URL is signed over those two headers and the host, so a different content-type or a content-length that does not match the bytes makes the signature invalid and object storage refuses the PUT. Do not send your API key to this URL — the capability is the credential, and the storage host has no use for a TAVONEL key.

# URL, TYPE and SIZE are capability.uploadUrl, capability.declaredMimeType and capability.contentLength.
curl -sS -X PUT "$URL" \
  -H "content-type: $TYPE" \
  -H "content-length: $SIZE" \
  --data-binary @manual.pdf
# 200 with an empty body. A 403 naming an expired request means the capability
# window closed: ask for a new one rather than retrying this URL.

import pathlib, urllib.request

body = pathlib.Path("manual.pdf").read_bytes()
put = urllib.request.Request(capability["uploadUrl"], data=body, method="PUT")
put.add_header("content-type", capability["declaredMimeType"])
put.add_header("content-length", str(capability["contentLength"]))
# The PUT is unauthenticated: the capability URL is the credential, and it is short-lived.
with urllib.request.urlopen(put, timeout=120) as response:
    assert response.status == 200, response.status

const bytes = await readFile("manual.pdf");
const put = await fetch(capability.uploadUrl, {
  method: "PUT",
  headers: { "content-type": capability.declaredMimeType },
  body: bytes, // its length is the content-length, and it must equal capability.contentLength
});
// No Authorization header here. The signed URL is the credential.
if (!put.ok) throw new Error(`upload failed: ${put.status}`);

POST/uploads/confirmScope documents:intake

After the PUT to `uploadUrl` succeeds, confirm the document with its `documentId` and the sha256 of the bytes you sent as `sourceSha256` (required on a free evaluation). The server checks the stored object's size, type and leading bytes against what the capability admitted and records the confirmation in one statement; the PUT response is not a confirmation. A digest that differs from one already recorded for the document is refused as SOURCE_DIGEST_CONFLICT.

curl -sS -X POST https://tavonel.com/api/v1/uploads/confirm \
  -H "Authorization: Bearer $TAVONEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "documentId": "<documentId>", "sourceSha256": "<sourceSha256>" }'

import os
import requests

body = {
    "documentId": "<documentId>",
    "sourceSha256": "<sourceSha256>"
}

response = requests.request(
    "POST",
    "https://tavonel.com/api/v1/uploads/confirm",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    json=body,
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/uploads/confirm", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ "documentId": "<documentId>", "sourceSha256": "<sourceSha256>" }),
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Request body

{
  "documentId": "<documentId>",
  "sourceSha256": "<sourceSha256>"
}

Status	Response
`200`	The admission receipt: `result.status` is confirmed for the `documentId` you named.
`400`	UPLOAD_CONFIRM_BODY_INVALID — The confirmation request did not identify a valid approved document. INVALID_SOURCE_DIGEST — The submitted content digest is not a valid SHA-256 identity. SOURCE_DIGEST_REQUIRED — An event carried bytes with no `contentSha256`.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns. API_KEY_INVALID — The bearer token was well-formed but did not match a stored key. API_KEY_EXPIRED — The key matched and its expiry has passed. API_KEY_REVOKED — The key matched and was revoked. A rotation revokes the key it replaces.
`403`	API_SCOPE_REQUIRED — The key authenticated and does not carry the scope this operation requires. The request was refused rather than answered with less. CUSTOMER_DATA_NOT_ENABLED_FOR_WORKSPACE — This workspace has no current approval to process its sources.
`409`	QUARANTINE_ADMISSION_NOT_FOUND — No matching intake admission exists for the approved document. QUARANTINE_OBJECT_NOT_FOUND — The uploaded object is absent, so confirmation or release cannot proceed as requested. CONTENT_LENGTH_MISMATCH — The body length did not match the declared `content-length`. OBSERVED_MIME_MISMATCH — The stored object's observed MIME type differs from the approved type. SOURCE_DIGEST_CONFLICT — Two events declare different digests for the same revision.
`413`	UPLOAD_CONFIRM_REQUEST_TOO_LARGE — The confirmation metadata exceeded the endpoint's bounded request size.
`429`	API_RATE_LIMITED — The key has used its per-minute allowance for this scope. The window is a fixed clock minute per key and scope; the allowances are on /docs/billing-and-limits. TRIAL_SOURCE_REVIEW_REQUIRED — A free-evaluation source was held for review by the risk gate.
`503`	SIGNER_NOT_CONFIGURED — The upload URL signer is not configured, so no capability can be issued. INTAKE_CONFIRMATION_NOT_CONFIGURED — The confirmation database connection is not configured. INTAKE_CONFIRMATION_FAILED — The atomic admission and approval confirmation could not be completed. INTAKE_CONFIRMATION_RECEIPT_INVALID — The database response did not prove that this approved member was atomically confirmed. API_RATE_LIMIT_UNAVAILABLE — The allowance could not be read, so the request was refused rather than run unbounded.

How long the URL lives, and what happens when it does not

Note expiresInSeconds in the capability response is the authority: the URL stops working that many seconds after the capability was issued, so read it rather than assume a number. The window is deliberately short: a signed URL is a credential that travels, and a long-lived one is a long-lived credential. After it passes, object storage refuses the PUT with its own expiry error and nothing was written; request a fresh capability for the same file. A document id issued for a capability that was never used carries no bytes, is never compiled, and needs no cleaning up.

The codes these endpoints return

Note 402 on the capability call is a plan or balance refusal — STUDIO_SUBSCRIPTION_REQUIRED, GPU_CREDITS_REQUIRED, or one of the TRIAL_ codes on a free evaluation. 429 is INTAKE_RATE_LIMITED (honour Retry-After: 60), INTAKE_DAILY_QUOTA_EXCEEDED (Retry-After: 3600), or API_RATE_LIMITED for the per-minute scope allowance. Every code named here is in the Errors catalogue with what to do about it.

API version 2026-09-02.1 · reviewed 11 September 2026

Something here out of date or wrong? Report an issue with this page.