Batch uploads

Use POST /v1/batch when you need to upload several files together. Authenticate with a bearer API key and send an Idempotency-Key header.

Create a batch

Send a manifest form part containing a JSON array. Each entry maps a form part name to a project path:

batch upload

curl -sS -X POST https://agentfs.cloud/v1/batch \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -H "Idempotency-Key: report-set-1" \
  -F 'manifest=[{"part":"summary","path":"research/summary.md"},{"part":"data","path":"research/data.csv"}]' \
  -F "summary=@./summary.md" \
  -F "data=@./data.csv"

Each part is 1–64 characters and may contain letters, numbers, _, and -. Each path must include a project and filename. The manifest must contain 1–25 entries, and part names must be unique. The request body and the summed file bytes are limited to 104,857,600 bytes (100 MiB).

The batch runs to completion inside the request. The response has status 200 and the final batch object:

{
  "type": "batch",
  "id": "b_4d2a",
  "status": "failed",
  "total": 2,
  "completed": 1,
  "failed": 1,
  "items": [
    {
      "part": "summary",
      "path": "research/summary.md",
      "file": {
        "type": "file",
        "id": "f_8f2c",
        "name": "summary.md",
        "path": "research/summary.md",
        "label": null,
        "content_type": "text/markdown",
        "content_disposition": "inline",
        "size_bytes": 8192,
        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
        "etag": "\"demo-etag\"",
        "revision": 1,
        "visibility": "unlisted",
        "expires_at": null,
        "tags": [],
        "metadata": {},
        "agent_id": null,
        "run_id": null,
        "url": "https://f.agentfsusercontent.com/f/f_8f2c",
        "markdown": "[summary.md](https://f.agentfsusercontent.com/f/f_8f2c)",
        "created_at": "2026-04-01T12:00:00.000Z",
        "updated_at": "2026-04-01T12:00:00.000Z"
      }
    },
    {
      "part": "data",
      "path": "research/data.csv",
      "error": {
        "code": "path_exists",
        "detail": "The path research/data.csv already exists."
      }
    }
  ],
  "created_at": "2026-04-01T12:00:00.000Z"
}

Each item has a file, an error, or a status. A failed item has this shape:

{
  "part": "data",
  "path": "research/data.csv",
  "error": {
    "code": "path_exists",
    "detail": "The path research/data.csv already exists."
  }
}

The batch status is completed when every file stored, and failed when any file did not. A batch can finish with some files completed and others failed, so check items rather than the status alone. Files use the project's defaults for visibility and expiry.

Retry safely

The Idempotency-Key is required and may contain up to 200 characters. Repeating the same key with the same manifest and file bytes returns the existing batch with status 200. Reusing it for a different request returns 409 idempotency_conflict.

Inspect a batch

Call GET /v1/batch/:id with the same key that created the batch:

curl -sS https://agentfs.cloud/v1/batch/b_4d2a \
  -H "Authorization: Bearer $AGENTFS_KEY"

Batch records are retained for 24 hours. An expired record returns 404 batch_not_found.

A batch cannot be cancelled: it has already finished by the time POST /v1/batch responds. To undo one, delete the files it stored.

Create a batch

Retry safely

Inspect a batch

On this page