Files
The agent's virtual file system, including its primary document and mind.
On this page
List the agent's files
/agents/{id}/filesPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Files (metadata) | AgentFilesResponse | ||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/files" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Read one file
/agents/{id}/files/contentText-like files come back as encoding: "utf-8" with content; binary files as encoding: "base64" with content_base64.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | File path inside the agent |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | File with content (utf-8) or content_base64 | FileContentResponse | ||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Errors 400 · 401 · 403 · 404
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/files/content?path=notes/today.md" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"agentId": "Xk3v9QpLm2",
"path": "mind.md",
"mime_type": "text/markdown",
"size": 12,
"protection": "none",
"authorized": false,
"created_at": "2026-09-01T10:00:00.000Z",
"updated_at": "2026-09-01T10:00:00.000Z",
"encoding": "utf-8",
"content": "# Mind\n"
}Write one file
/agents/{id}/files/contentText with content, binary with content_base64 (plus mime_type). Fires the agent's file-change triggers.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | File path inside the agent |
baseRevision | integer | W3-F: write only over this revision of the resource (from a read or the last write). Another current revision answers 409 |
Header parameters
| Name | Type | Description |
|---|---|---|
If-Match | string | W3-F: the base revision, as |
If-None-Match | string | W3-F: |
Request bodyapplication/json · FileWriteBody · required
One of content / content_base64 is required.
| Field | Type | Description |
|---|---|---|
content | string | Text content |
content_base64 | string | Binary content (alias: contentBase64) |
contentBase64 | string | |
mime_type | string | Alias: mimeType |
mimeType | string | |
protection | string | |
baseRevision | integer | W3-F: write only over this revision (else 409 stale_revision); as the |
mustNotExist | boolean | W3-F: create only: refused (409 stale_revision, with the existing file's revision) when the file exists. As |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Written | RevisionedSuccess | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | ||||||||||||||||||||||||||||||||||
| 401 | Missing or wrong bearer token (unauthorized) | ||||||||||||||||||||||||||||||||||
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | ||||||||||||||||||||||||||||||||||
| 404 | Unknown agent (or the named resource: loop, task, file, …) | ||||||||||||||||||||||||||||||||||
| 409 | W3-F: the resource changed since the write's base revision (stale_revision); nothing was written. A write to a document another runtime holds answers 409 agent_leased (or file_moving during a move) instead. | StaleRevisionError | |||||||||||||||||||||||||||||||||
sizeinteger | null | Current size in bytes (null for config) hashrequiredstring | sha1 of the current content ( | |||||||||||||||||||||||||||||||||
| 500 | Unexpected runtime failure | ||||||||||||||||||||||||||||||||||
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/agents/agent-1/files/content?path=notes/today.md" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"hello\n","mime_type":"text/plain"}'Delete one file
/agents/{id}/files/contentPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | File path inside the agent |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | success is false when nothing was deleted | AgentSuccess | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/files/content?path=notes/today.md" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"agentId": "Xk3v9QpLm2",
"success": true
}Rename a file
/agents/{id}/files/renamePath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Request bodyapplication/json · FileRenameBody · required
| Field | Type | Description |
|---|---|---|
oldPathrequired | string | |
newPathrequired | string |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Renamed | AgentSuccess | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/files/rename" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"oldPath":"string","newPath":"string"}'{
"agentId": "Xk3v9QpLm2",
"success": true
}Rename a folder (path prefix)
/agents/{id}/files/rename-folderPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Request bodyapplication/json · FolderRenameBody · required
| Field | Type | Description |
|---|---|---|
oldPrefixrequired | string | |
newPrefixrequired | string |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Renamed | FolderRenameResponse | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/files/rename-folder" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"oldPrefix":"string","newPrefix":"string"}'Set a file's protection
/agents/{id}/files/protectionPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Request bodyapplication/json · FileProtectionBody · required
| Field | Type | Description |
|---|---|---|
pathrequired | string | |
protectionrequired | string |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Saved | AgentSuccess | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PATCH "http://127.0.0.1:7385/agents/agent-1/files/protection" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"string","protection":"none"}'{
"agentId": "Xk3v9QpLm2",
"success": true
}Mark a file as authorized code (or not)
/agents/{id}/files/authorizedPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Request bodyapplication/json · FileAuthorizedBody · required
| Field | Type | Description |
|---|---|---|
pathrequired | string | |
authorizedrequired | boolean |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Saved | AgentSuccess | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PATCH "http://127.0.0.1:7385/agents/agent-1/files/authorized" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"string","authorized":true}'{
"agentId": "Xk3v9QpLm2",
"success": true
}Read the primary document
/agents/{id}/documentPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Content | TextContentResponse | |||||||||
| |||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/document" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Write the primary document
/agents/{id}/documentFires the agent's file/document-change triggers.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
baseRevision | integer | W3-F: write only over this revision of the resource (from a read or the last write). Another current revision answers 409 |
Header parameters
| Name | Type | Description |
|---|---|---|
If-Match | string | W3-F: the base revision, as |
Request bodyapplication/json · TextContentBody · required
| Field | Type | Description |
|---|---|---|
contentrequired | string | |
baseRevision | integer | W3-F: write only over this revision (else 409 stale_revision); as the |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Saved | RevisionedSuccess | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | W3-F: the resource changed since the write's base revision (stale_revision); nothing was written. A write to a document another runtime holds answers 409 agent_leased (or file_moving during a move) instead. | StaleRevisionError |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/agents/agent-1/document" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"# Notes\n"}'Read mind.md
/agents/{id}/mindPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Content | TextContentResponse | |||||||||
| |||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/mind" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Write mind.md
/agents/{id}/mindPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
baseRevision | integer | W3-F: write only over this revision of the resource (from a read or the last write). Another current revision answers 409 |
Header parameters
| Name | Type | Description |
|---|---|---|
If-Match | string | W3-F: the base revision, as |
Request bodyapplication/json · TextContentBody · required
| Field | Type | Description |
|---|---|---|
contentrequired | string | |
baseRevision | integer | W3-F: write only over this revision (else 409 stale_revision); as the |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Saved | RevisionedSuccess | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | W3-F: the resource changed since the write's base revision (stale_revision); nothing was written. A write to a document another runtime holds answers 409 agent_leased (or file_moving during a move) instead. | StaleRevisionError |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/agents/agent-1/mind" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"# Notes\n"}'Read an internal file's metadata
/agents/{id}/files/metaSize, MIME type, protection and whether Studio reads it as text, without the content: a client decides before fetching bytes (GET …/files/raw with maxBytes).
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | File path inside the agent |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Metadata | InternalFileMeta | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
Errors 400 · 401 · 403 · 404
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/files/meta?path=notes/today.md" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Download an internal file's bytes
/agents/{id}/files/rawThe content as application/octet-stream (Content-Type is the file's MIME type). With maxBytes, a larger file answers 413 too_large with its size, before any byte is read.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | File path inside the agent |
maxBytes | integer |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The file | string |
Errors 400 · 401 · 403 · 404 · 413
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 413 | Larger than maxBytes |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/files/raw?path=notes/today.md" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Upload an internal file's bytes
/agents/{id}/files/rawAfter receiving the body, the daemon revalidates the document and holds its lease through the write. A file moved while streaming returns 409 file_moving; a closed document returns 404; a lease acquired by another runtime returns 409 agent_leased. The body is the content (application/octet-stream, up to 64 MiB; ADF_DAEMON_RAW_BODY_LIMIT_MB). mimeType defaults by extension. unique=true keeps an existing file of that name and numbers the new one (the saved path is returned). 413 too_large, 415 for another content type. W3-F, as PUT /agents/{id}/files/content: a base revision (If-Match or baseRevision) that is not current, or a create (If-None-Match: * or mustNotExist=true) of a file that exists, answers 409 stale_revision and writes nothing; neither is taken with unique=true. The file_updated the write raises is not sent to the session named by X-ADF-Client-Session.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | File path inside the agent |
mimeType | string | |
unique | string | |
baseRevision | integer | W3-F: write only over this revision of the resource (from a read or the last write). Another current revision answers 409 |
mustNotExist | string | W3-F: create only, as If-None-Match: *: refused (409 stale_revision) when the file exists |
Header parameters
| Name | Type | Description |
|---|---|---|
If-Match | string | W3-F: the base revision, as |
If-None-Match | string | W3-F: |
Request bodyapplication/octet-stream · string · required
No fields.
Responses
| Status | Description | Body | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Written | RawFileWriteResult | |||||||||||||||
| |||||||||||||||||
Errors 400 · 401 · 403 · 404 · 409 · 413 · 415 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The resource is in a state that does not allow this now | |
| 413 | Larger than the upload limit | |
| 415 | Not application/octet-stream | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/agents/agent-1/files/raw?path=notes/today.md" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/octet-stream" \
-d '"string"'