Files

Operations tagged Files in the public API.

About Files

A file is a document you upload with POST /files to turn it into knowledge with POST /knowledge (name and file_id). Uploading stores it and emits file.created; it trains nothing until a dataset is created from it. Accepted: txt, pdf, doc, docx, rtf and odt documents, png, jpg, jpeg and webp images (read by OCR, as are scanned PDFs) and xlsx, xls, csv and ods spreadsheets — at most 10 MB each, and 20 files or 90 MB per batch, by default. The content must match the extension.

A file backs at most one dataset (knowledge_dataset_id): naming it in a second POST /knowledge is 409 FILE_ALREADY_ATTACHED. While it backs one it cannot be deleted (409 FILE_BACKS_DATASET): delete the dataset instead, which deletes its file with it.

IDs you will meet.

id — the file id, an integer: the file_id POST /knowledge takes.
file_id on the file object — a UUID, informational only.
knowledge_dataset_id — the dataset made from the file.

IDs on this page

File id<FILE_ID>: Integer: the file's id. The UUID in its file_id field is not accepted here.
Get it from
POST /v1/files returns it as id
POST /v1/files returns it as data[].id
GET /v1/files returns it as data[].id
Webhook file.created carries it as data.object.id

/v1/files

List files

Returns the account's uploaded files, newest first and cursor-paginated — those uploaded with POST /files and those behind datasets created from the dashboard or a cloud import. knowledge_dataset_id is set on each file that backs a dataset.

Required scope: files:read
Idempotency: Read-only
Rate limits

Query parameters

limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of FileResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
Always/v1/files
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/files' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "file",
      "id": 1,
      "file_id": "0b6f2f4e-8a71-4c55-9d1e-3c2a7b9e5f10",
      "filename": "refund-policy.pdf",
      "mime_type": "application/pdf",
      "extension": "pdf",
      "size_bytes": 48213,
      "status": "uploaded",
      "knowledge_dataset_id": 1,
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/files"
}

/v1/files

Upload one or more files

Stores files as multipart form data so you can create knowledge from them: pass each returned id to POST /knowledge as file_id. Uploading trains nothing by itself, and each file emits file.created. Send a single file — answered with a file object — or a files[] batch, answered with a list; a batch is stored all or nothing, under one Idempotency-Key. The type is checked by extension and by content (a binary renamed .txt is 422 VALIDATION_FAILED); the size and batch limits are on the fields.

Required scope: files:write
Idempotency: Accepts Idempotency-Key
Webhook events: file.created
Rate limits

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

Body for POST /v1/files. Accepts either a single file or a files[] batch. The dashboard has always had a multi-file upload; the API forced one request per file, so importing a folder of PDFs meant N round trips, N idempotency keys, and no way to treat the import as one unit.

filestringOptional
One file: txt, pdf, doc, docx, rtf, odt, png, jpg, jpeg, webp, xlsx, xls, csv or ods, at most 10 MB by default. Its content must match its extension (a binary renamed .txt is 422). Send this or files[]; when both are sent only file is stored.
Format: binary
filesarray of stringOptional
A batch of files with the same type and size rules: at most 20 files and 90 MB together by default. The batch is stored all or nothing, and one Idempotency-Key covers it.
Min items: 1Max items: 20

Responses

201
FileResource
any of
Shape 1object
objectstringRequired
Alwayslist
dataarray of FileResourceRequired
has_morebooleanRequired
next_cursoranynullableRequired
previous_cursoranynullableRequired
urlstringRequired
Always/v1/files
Shape 2FileResource
objectstringRequired
Alwaysfile
idintegerRequired
The file id. Pass it as file_id to POST /knowledge.
file_idstringRequired
The file's UUID. Informational: every /v1 operation takes the integer id.
filenamestringRequired
The name the file was uploaded with.
mime_typestringRequired
The MIME type detected from the file's content.
extensionstringRequired
The lower-case extension of the uploaded name, without the dot; bin when the name has none.
size_bytesintegerRequired
Size in bytes.
statusstringRequired
uploaded (stored), processing, processed, failed or archived (replaced by POST /knowledge/{id}/replace_file).
Possible valuesuploadedprocessingprocessedfailedarchived
knowledge_dataset_idintegernullableRequired
The knowledge dataset created from this file; null while the file backs none. A file backs at most one dataset.
created_atstringnullableRequired
When the file was uploaded (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/files' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "file": "file",
  "files": []
}'

Response

Example 201 response

json

{
  "object": "file",
  "id": 1,
  "file_id": "0b6f2f4e-8a71-4c55-9d1e-3c2a7b9e5f10",
  "filename": "price-list.txt",
  "mime_type": "text/plain",
  "extension": "txt",
  "size_bytes": 56,
  "status": "uploaded",
  "knowledge_dataset_id": null,
  "created_at": "2026-01-01T00:00:00+00:00"
}

/v1/files/{id}

Retrieve a file

Returns one file's metadata — name, MIME type, size, status and the dataset it backs (knowledge_dataset_id). /v1 does not return the file's bytes.

Required scope: files:read
Idempotency: Read-only
Rate limits

Before you call

id(path)File id
Integer: the file's id. The UUID in its file_id field is not accepted here.
Placeholder in the samples: <FILE_ID>
Get it from
- POST /v1/files returns it as id
- POST /v1/files returns it as data[].id
- GET /v1/files returns it as data[].id
- Webhook file.created carries it as data.object.id

Path parameters

idintegerRequired
The file id.

Responses

200
FileResource
objectstringRequired
Alwaysfile
idintegerRequired
The file id. Pass it as file_id to POST /knowledge.
file_idstringRequired
The file's UUID. Informational: every /v1 operation takes the integer id.
filenamestringRequired
The name the file was uploaded with.
mime_typestringRequired
The MIME type detected from the file's content.
extensionstringRequired
The lower-case extension of the uploaded name, without the dot; bin when the name has none.
size_bytesintegerRequired
Size in bytes.
statusstringRequired
uploaded (stored), processing, processed, failed or archived (replaced by POST /knowledge/{id}/replace_file).
Possible valuesuploadedprocessingprocessedfailedarchived
knowledge_dataset_idintegernullableRequired
The knowledge dataset created from this file; null while the file backs none. A file backs at most one dataset.
created_atstringnullableRequired
When the file was uploaded (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/files/<FILE_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "file",
  "id": 1,
  "file_id": "0b6f2f4e-8a71-4c55-9d1e-3c2a7b9e5f10",
  "filename": "refund-policy.pdf",
  "mime_type": "application/pdf",
  "extension": "pdf",
  "size_bytes": 48213,
  "status": "uploaded",
  "knowledge_dataset_id": 1,
  "created_at": "2026-01-01T00:00:00+00:00"
}

/v1/files/{id}

Delete a file

Deletes an uploaded file and its stored bytes, and emits file.deleted. A file that still backs a knowledge dataset is 409 FILE_BACKS_DATASET (details.dataset_id), and nothing changes: delete that dataset instead (DELETE /knowledge/{id}), which deletes its file with it.

Required scope: files:write
Idempotency: Accepts Idempotency-Key
Webhook events: file.deleted
Rate limits

Before you call

id(path)File id
Integer: the file's id. The UUID in its file_id field is not accepted here.
Placeholder in the samples: <FILE_ID>
Get it from
- POST /v1/files returns it as id
- POST /v1/files returns it as data[].id
- GET /v1/files returns it as data[].id
- Webhook file.created carries it as data.object.id

Path parameters

idintegerRequired
The file id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwaysfile
idintegerRequired
The file id.
deletedbooleanRequired
Always true.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesFILE_BACKS_DATASET IDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/files/<FILE_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "file",
  "id": 1,
  "deleted": true
}

About Files

IDs you will meet.

id — the file id, an integer: the file_id POST /knowledge takes.
file_id on the file object — a UUID, informational only.
knowledge_dataset_id — the dataset made from the file.

{ "object": "list", "data": [ { "object": "file", "id": 1, "file_id": "0b6f2f4e-8a71-4c55-9d1e-3c2a7b9e5f10", "filename": "refund-policy.pdf", "mime_type": "application/pdf", "extension": "pdf", "size_bytes": 48213, "status": "uploaded", "knowledge_dataset_id": 1, "created_at": "2026-01-01T00:00:00+00:00" } ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/files" }

{ "object": "file", "id": 1, "file_id": "0b6f2f4e-8a71-4c55-9d1e-3c2a7b9e5f10", "filename": "price-list.txt", "mime_type": "text/plain", "extension": "txt", "size_bytes": 56, "status": "uploaded", "knowledge_dataset_id": null, "created_at": "2026-01-01T00:00:00+00:00" }

{ "object": "file", "id": 1, "file_id": "0b6f2f4e-8a71-4c55-9d1e-3c2a7b9e5f10", "filename": "refund-policy.pdf", "mime_type": "application/pdf", "extension": "pdf", "size_bytes": 48213, "status": "uploaded", "knowledge_dataset_id": 1, "created_at": "2026-01-01T00:00:00+00:00" }

About Files

IDs on this page

/v1/files

Query parameters

Responses

See also

Request

Response

/v1/files

Header parameters

Request body

Responses

See also

Request

Response

/v1/files/{id}

Path parameters

Responses

See also

Request

Response

/v1/files/{id}

Path parameters

Header parameters

Responses

See also

Request

Response

About Files

IDs on this page

/v1/files

Query parameters

Responses

See also

Request

Response

/v1/files

Header parameters

Request body

Responses

See also

Request

Response

/v1/files/{id}

Path parameters

Responses

See also

Request

Response

/v1/files/{id}

Path parameters

Header parameters

Responses

See also

Request

Response