Upload

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

Note Before you start. A finished Compiled World is open to read in full today, with its evidence attached. Compiling your own sources is set up with us rather than enabled by a plan purchase. Everything on this page is the contract the capability endpoint serves once intake is arranged; it is not a request TAVONEL will accept from you today.

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.

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());

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

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());

The PUT itself

The capability response carries url, method, headers and expiresAt. Send exactly the headers it lists and no others: the URL is signed over that header set, so an extra header, 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.url, capability.headers and requestedBytes.
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["url"], data=body, method="PUT")
for name, value in capability["headers"].items():
    put.add_header(name, value)
# 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.url, {
  method: capability.method,
  headers: capability.headers,
  body: bytes,
});
// No Authorization header here. The signed URL is the credential.
if (!put.ok) throw new Error(`upload failed: ${put.status}`);

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

Note expiresAt in the capability response is the authority, and it is an absolute instant rather than a duration — read it, do not 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.