Files

List files

List files. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopefiles:read

{
  "object": "list",
  "data": [
    {
      "object": "file",
      "id": 1,
      "file_id": "8bf1b235-6180-4b5b-a363-ac6026e0ecdc",
      "filename": "provident-laudantium.pdf",
      "mime_type": "application/pdf",
      "extension": "pdf",
      "size_bytes": 1925899,
      "status": "uploaded",
      "knowledge_dataset_id": 2,
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/files"
}

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

Upload one or more files

Send a single `file`, or a `files[]` batch under one Idempotency-Key. Each returned file id can be passed to `POST /v1/knowledge` as `file_id`. A single upload answers with a file object; a batch answers with a list, so a client can tell the two apart without inspecting the request it sent.

Required scopefiles:write

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

Retrieve a file

Retrieve a file. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopefiles:read

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

Delete a file

Delete a file. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopefiles:write

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