API reference

Call the API at https://agentfs.cloud.

This guide explains the shared behavior of the API. For generated, endpoint-by-endpoint request and response details, use the Endpoint reference section in the sidebar.

Authentication

Send an API key in the Authorization header:

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

Use the device authorization flow to connect an agent and receive a key. The server accepts the key only in the Bearer <key> form. A missing or invalid key returns unauthorized.

Most /v1 endpoints require an API key. The exceptions are:

• GET /v1/me returns an unauthenticated response when you omit Authorization.
• The device authorization endpoints have their own authentication rules.
• The multipart upload endpoints also accept an authenticated browser session when no Authorization header is present.

API key permissions

A key carries one or more scopes. A scope can cover the whole organization, a project, or a path prefix within a project.

The required permission depends on the endpoint. File reads and listings use read; uploads and project updates use write; file and upload deletion use delete; temporary file access URLs use share. Creating a project requires organization-level write. Batch reads and writes check every path in the batch.

Requests and responses

Send JSON with Content-Type: application/json where an endpoint documents a JSON body. Use multipart/form-data for one-shot files and batches. Multipart upload parts use a binary request body.

Successful JSON responses use application/json. A successful 204 response has no body.

Errors use application/problem+json and have this shape:

{
  "type": "https://agentfs.cloud/docs/errors#invalid-path",
  "title": "invalid_path",
  "status": 400,
  "code": "invalid_path",
  "detail": "Path segments are malformed.",
  "retryable": false
}

detail is omitted when the handler does not provide one. retryable is true for status codes from 500 through 599, and for 429. It is false otherwise. Every 429 and 503 carries a Retry-After header in seconds. Retry 408, 429, and 5xx with exponential backoff; see Retries. See the errors guide for the error catalog.

Rate limits

/v1 requests carrying an Authorization header are counted per key: 600 requests per 60 seconds. Uploads without a key to POST /v1/files are counted per IP address: 20 per 60 seconds. POST /v1/auth/device is counted per IP address: 10 per 60 seconds.

Over a limit, the response is 429 rate_limited with retryable: true and a Retry-After header in seconds. Wait for it and retry the same request.

Pagination

GET /v1/files and GET /v1/projects accept limit and cursor. limit defaults to 50 and must be an integer from 1 through 200. Pass the returned next_cursor as the next request's cursor. Cursors are opaque. A malformed cursor returns invalid_query; project listing also rejects a syntactically valid cursor that is not in the visible collection.

{
  "items": [],
  "next_cursor": null
}

GET /v1/events pages the other way. It is a forward feed: it reads oldest first, takes its cursor as after, and returns next_cursor on every non-empty page so an agent can keep polling from the last one it saw.

Idempotency

POST /v1/files accepts an optional Idempotency-Key header with 1–200 characters. Repeating the key with the same upload returns the existing file with 201; changing the request for the same key returns idempotency_conflict. Uploads without an API key cannot send it.

POST /v1/batch requires Idempotency-Key with at most 200 characters. Repeating it with a different manifest returns idempotency_conflict. Batch responses use 200, including when the existing batch is returned.

POST /v1/files with if_exists=replace is safe to retry without a key: writing the same bytes to the same path again returns the current file unchanged.

Agent and run headers

When you authenticate with an API key, you may send these printable labels:

The values are trimmed and must contain at least one printable character. An invalid value returns invalid_agent_label. These headers identify a request; they do not authenticate it. The API does not return a separate request ID header.

A file records the X-Agent-ID and X-Run-ID of the request that created it, as agent_id and run_id on the file object. Both are list filters: GET /v1/files?run_id=... returns everything one run wrote.

Paths

File paths use the form project/filename or project/folder/filename; responses omit the leading slash. Leading and repeated slashes are normalized. Each segment may contain only letters, digits, ., _, and -. The parser allows at most 16 segments and 2,048 encoded characters. The first segment is the project name. A path that names a project not yet present can create that project when the key has organization-level write permission.