---
title: "Create an upload session"
description: "Prepare a temporary upload URL and upload-only headers for a local document, including the requirements for an MCP agent."
canonical: "https://ai-glot.com/docs/api/uploads/create"
updated: "2026-10-02"
---

# Create an upload session

Requires `batches:create`. Creating a session costs no credits and does not create a translation. Send a bare filename with its supported extension and the exact size of the original bytes:

```json
{ "filename": "catalogue.xlsx", "size_bytes": 4096 }
```

The response contains `upload_id`, `upload_url`, `method`, `headers`, `expires_at`, `consume_until` and human-readable `instructions`. Use the returned URL and headers exactly with an external HTTP client, then [create the translation](/docs/api/translations/create) with `upload_id` on the same credential. The filename is already attached to the session.

```javascript
const session = createUploadResponse.data;
const uploaded = await fetch(session.upload_url, {
  method: session.method,
  headers: session.headers,
  body: originalFileBytes,
  redirect: "error",
});
if (!uploaded.ok) throw new Error(`Upload failed: ${uploaded.status}`);
// Use the original workspace credential for POST /v1/batches:
// { upload_id: session.upload_id, instruction: "Translate into French" }
```

The temporary `Authorization` header grants only one upload attempt for this document within 10 minutes. The URL alone grants no access. Never replace that header with a workspace API key or OAuth token, put secrets in a URL, follow redirects, or log the temporary headers. The upload secret cannot read documents, create translations or approve spending. Revoking the connection or removing its permission invalidates its unused upload capabilities.

The received byte count must match `size_bytes`; the per-format limit is checked before the capability is issued. Create the translation within one hour. A workspace can have 20 pending uploads and create 120 sessions per hour. Unused files are eligible for cleanup after 24 hours and collected by the daily sweep. Once a translation owns the file, its normal retention applies. Recovery by upload\_id is available until session cleanup, at least 24 hours after issuance. Keep the batch ID to retrieve the translation from your history afterwards.

## Requirements for agents

The agent runtime needs local file access and an HTTP client that can send raw PUT requests. MCP alone cannot send binary bytes, and AI Glot Code Mode has no local file access or outbound HTTP. If those capabilities are missing, tell the user plainly that the assistant cannot send the attachment. Recommend uploading in the AI Glot web app, using the CLI, or providing an HTTPS download link for `file_url`. Never claim that an upload succeeded without verifying it.

After upload, review the translation plan and its exclusions before approving the credit cost. [Send raw bytes](/docs/api/uploads/send) describes retries and failures.