Agent files
Agent files on the daemon host: the path → id rule, delete, rename, clone, accept-relocate, snapshots (share, export, save as), import, the daemon-side folder picker, raw transfers of an agent's internal files, and the operations Studio runs on agent files that are not loaded (/files/agent/*). Every agent file argument is an absolute path ending in .adf.
On this page
Resolve an agent file path to its agent id
/files/agentThe path → id rule for clients that address agents by file path (ADF Studio). loaded: true: use the /agents/{id} routes with agentId. loaded: false: the /agents/{id} routes answer 404 for this agent; use the /files/agent/* routes with the path.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The file | PathAgentInfo | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
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/files/agent?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"An agent file's config by path
/files/agent/configThe live config of a running agent or open document; any other file is read through one readonly connection (nothing written). Same path rules as the other /files routes. Credential values are identity rows, not config.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The config | AgentFileConfigResponse | ||||||||||||
| ||||||||||||||
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 "http://127.0.0.1:7385/files/agent/config?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Where new and accepted agents go
/files/agents-foldersettings.agentsFolder (ignored when it points into the OS temp folder), else <Documents>/adf-agents. Needs no owner identity. Not created by this call.
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The agents folder | AgentsFolderInfo | |||||||||
| |||||||||||
Errors 401 · 403
| 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 |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/files/agents-folder" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Delete an agent file
/filesAs ADF Studio deletes: an agent running in this daemon is stopped first (unregistered from the mesh, lease released; 409 stop_timeout when it does not stop within 15 s, the file is then kept), then the file and its -wal/-shm sidecars are deleted. A file that is already gone is not an error. 409 agent_leased while another runtime runs it, file_busy when another process holds the file open; 400 path_not_canonical for a path through a link or alias. Agent file paths are canonicalized; the path must name an .adf before and after links and short names are resolved. Refused (400): alternate data streams, device paths, reserved device names, UNC paths outside the tracked folders (bad_path, unc_not_allowed, not_an_adf).
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Deleted | FileDeleteResult | ||||||||||||
| ||||||||||||||
Errors 400 · 401 · 403 · 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 | |
| 409 | The file is in use by another process | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/files?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Rename an agent file
/files/renameA stopped agent's file is renamed now (WAL folded in first) and its config name set to match; file_renamed is pushed. A running agent keeps running under its file, lease and mesh registration: its name changes now and the file moves when it stops (renameDeferred: true), as in ADF Studio. 400 invalid_name, 409 name_taken, 409 file_busy. 409 agent_leased while another runtime runs it; 400 path_not_canonical for a path through a link or alias. The move does not autostart the agent.
Request bodyapplication/json · AgentFileRenameBody · required
| Field | Type | Description |
|---|---|---|
pathrequired | string | |
newNamerequired | string | File name without .adf; no path separators |
Responses
| Status | Description | Body | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Renamed or deferred | AgentFileRenameResult | ||||||||||||
| ||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/rename" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"string","newName":"string"}'Clone an agent file
/files/cloneCopies the selected tables into <name>_clone.adf next to the source, with a new config.id, a fresh identity unless adf_identity is kept, and the source as parent (clone-fixup). The clone is marked reviewed; an untracked folder becomes tracked. 409 identity_not_ready while the owner identity is not set up.
Request bodyapplication/json · AgentFileCloneBody · required
| Field | Type | Description |
|---|---|---|
pathrequired | string | |
selectedTablesrequired | array<string> | Tables to keep (GET /files/agent/tables); without adf_identity the clone gets a fresh identity |
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 201 | Cloned | AgentFileCloneResult | ||||||||||||||||||
| ||||||||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/clone" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"string","selectedTables":[]}'Move an accepted agent file into the agents folder
/files/relocateThe accept step for a file outside every tracked folder (a temp attachment, Downloads): it moves into the agents folder, which is tracked, and file_renamed is pushed. A failed move never fails: the file's own folder is tracked instead, except an OS temp folder (moveError). A file inside a tracked folder stays ({}). The caller releases its handles on the file first. A file another runtime runs is not moved.
Request bodyapplication/json · AgentFilePathBody · required
| Field | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Moved, or why not | AgentFileRelocateResult | ||||||
| ||||||||
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/files/relocate" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"string"}'Write a snapshot of an agent file to another path
/files/save-asStudio's Save a copy…: the identity-free share snapshot, built on a .partial and moved into place. 400 export_not_supported for mode export. 409 same_file for the source itself, name_taken when the destination exists without overwrite (also when it appears while the copy is written), agent_running / agent_leased when the destination is a running agent, document_open when it is open here as a document.
Request bodyapplication/json · AgentFileSaveAsBody · required
| Field | Type | Description |
|---|---|---|
pathrequired | string | |
destPathrequired | string | Absolute .adf path on the daemon host; its folder must exist |
mode | string | Only |
overwrite | boolean |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Written | AgentFileSaveAsResult | |||||||||
| |||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/save-as" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"string","destPath":"string"}'Download a snapshot of an agent file
/files/snapshotshare (default): the identity-free copy Studio's Share and Save a copy… make. export: the whole file, which holds the agent's identity: local callers with this run's X-ADF-Local-Proof only, in every mode (403 loopback_only otherwise; see Local-only routes), and without its plain secrets (a legacy agent's plain crypto:signing:private_key, plain credential values; header X-ADF-Export-Secrets: removed) unless includeSecrets=true (X-ADF-Export-Secrets: included). Sealed rows, the public key, envelope descriptors and KDF parameters stay. Both are consistent while the agent runs (SQLite online backup) and travel as one file (rollback journal mode).
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
mode | string | |
includeSecrets | boolean |
|
Header parameters
| Name | Type | Description |
|---|---|---|
X-ADF-Local-Proof | string | Required for |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The file | string |
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 "http://127.0.0.1:7385/files/snapshot?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Export an agent's file
/agents/{id}/exportA consistent copy of the agent's whole .adf (SQLite online backup), also while it runs and writes. The agent may be loaded, or a file in a tracked folder with that config id. The file holds the agent's identity, so this route answers local callers with this run's X-ADF-Local-Proof only, in every mode (403 loopback_only otherwise; see Local-only routes). Plain secrets (a legacy agent's plain crypto:signing:private_key, plain credential values) are left out (X-ADF-Export-Secrets: removed) unless includeSecrets=true (X-ADF-Export-Secrets: included). 409 not_file_backed for an in-memory agent.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
includeSecrets | boolean | Keep the plain secrets (a legacy agent's plain signing key, plain credential values) in the copy. |
Header parameters
| Name | Type | Description |
|---|---|---|
X-ADF-Local-Proofrequired | string | The contents of |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The file | string |
Errors 401 · 403 · 404 · 409 · 500
| 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 | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/export" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Upload an .adf into a tracked folder
/files/importThe body is the file (application/octet-stream, up to 1 GiB; ADF_DAEMON_IMPORT_BODY_LIMIT_MB). It lands in directory, which must be a tracked folder or inside one, or the agents folder (the default; tracked then). The file is never treated as reviewed and the watcher does not autostart it. An upload whose config id or DID matches an agent known here (reviewed, loaded, or in a tracked folder) gets a fresh id and loses its identity (idReassigned). 400 not_an_adf, invalid_name; 403 outside_tracked; 409 name_taken (send unique=true for "name (2).adf"); 413 too_large; 415 for another content type.
Query parameters
| Name | Type | Description |
|---|---|---|
directory | string | Target folder (absolute); default the agents folder |
namerequired | string | File name, with or without .adf |
unique | string |
Request bodyapplication/octet-stream · string · required
No fields.
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 201 | Imported | AgentFileImportResult | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
Errors 400 · 401 · 403 · 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 | |
| 409 | The resource is in a state that does not allow this now | |
| 413 | Larger than the import limit | |
| 415 | Not application/octet-stream | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/import?name=NAME" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/octet-stream" \
-d '"string"'List a folder for a daemon-side picker
/fs/browseFolders and .adf files only, never other files; dot entries only with showHidden=true. Without path: the roots. A folder is listed only when it (after resolving links) is inside a root: the OS user's home folder, the tracked folders and the agents folder. ADF_DAEMON_BROWSE_ROOTS, when set, replaces the home folder with the folders it names (empty: tracked folders and agents folder only). A link that resolves outside every root is not listed. 403 outside_roots, 400 not_a_directory.
Query parameters
| Name | Type | Description |
|---|---|---|
path | string | Absolute folder path |
showHidden | string |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The folder | BrowseResult | ||||||||||||||||||||||||||||||||||||||||||
entriesrequiredarray<object> | 5 fields of | |||||||||||||||||||||||||||||||||||||||||||
namerequired | string | |
pathrequired | string | |
kindrequired | string | |
size | integer | |
mtimeMs | number |
truncatedrequiredMore than 2000 entries; the rest are not listed
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/fs/browse" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Tables of an agent file with row counts
/files/agent/tablesEvery table without the shadow tables of virtual (full-text) tables: the clone dialog's list. A file that is not loaded is read through one readonly connection (nothing written; sealed values read as locked).
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Tables | AgentFileTablesResult | ||||||||||||||||||
| ||||||||||||||||||||
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 "http://127.0.0.1:7385/files/agent/tables?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Set the model of a stopped agent file
/files/agent/modelThe provider must be configured in settings (400 provider_unknown). A loaded agent is refused (409 agent_running): save its config with PUT /agents/{id}/config. A file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · AgentFileModelBody · required
| Field | Type | Description |
|---|---|---|
providerrequired | string | A provider id configured in settings |
model_idrequired | string |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Set | AgentFileModelResult | |||||||||
| |||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/files/agent/model?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"provider":"string","model_id":"string"}'Store a provider API key in an agent file
/files/agent/providers/{providerId}/credentialPUT /agents/{id}/providers/{providerId}/credential by file path; works on a file that is not loaded. Same locked-envelope rules (409 credentials_locked, replace: true). A file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Path parameters
| Name | Type | Description |
|---|---|---|
providerIdrequired | string | Provider id in the agent config |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · IdentityValueBody · required
| Field | Type | Description |
|---|---|---|
valuerequired | string | |
replace | boolean | Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs ( |
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Stored | object | ||||||||||||||||||
| ||||||||||||||||||||
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 | Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (credentials_locked): unlock the owner identity, or retry with replace: true. A legacy agent locked with a whole-file password answers 409 credentials_locked until POST /agents/{id}/identity/password/unlock. An envelope refusal also names purpose, sealed (a value is stored sealed here: a replace discards it unread) and envelopeState (locked or foreign); choose on these, not on the message. | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/files/agent/providers/anthropic/credential?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"value":"sk-…"}'Store the app provider's key as an agent file's provider key
/files/agent/providers/{providerId}/credential/copy-app-keyStudio's "Copy app key": the app provider with this id (Settings → Providers) gives its API key, which a client only ever sees as __redacted__, and the daemon stores it as provider:{providerId}:apiKey in the file. Same locked-envelope rules as PUT /files/agent/providers/{providerId}/credential (409 credentials_locked, replace: true); a file that is not loaded is refused with 409 agent_leased while another runtime runs it. 409 no_app_key when the app provider is unknown or has no key.
Path parameters
| Name | Type | Description |
|---|---|---|
providerIdrequired | string | Provider id in the agent config |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · object · optional
| Field | Type | Description |
|---|---|---|
replace | boolean | Store it although the credentials envelope is locked here (a locked sealed value is discarded). |
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Stored | object | ||||||||||||||||||
| ||||||||||||||||||||
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 | Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (credentials_locked): unlock the owner identity, or retry with replace: true. A legacy agent locked with a whole-file password answers 409 credentials_locked until POST /agents/{id}/identity/password/unlock. An envelope refusal also names purpose, sealed (a value is stored sealed here: a replace discards it unread) and envelopeState (locked or foreign); choose on these, not on the message. | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/agent/providers/anthropic/credential/copy-app-key?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Provider credential metadata of an agent file
/files/agent/providers/{providerId}/credentialsMetadata only, never the value. A file that is not loaded is read through one readonly connection (nothing written; sealed values read as locked).
Path parameters
| Name | Type | Description |
|---|---|---|
providerIdrequired | string | Provider id in the agent config |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Metadata | object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
providerConfigobject | 3 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
defaultModel | string | |||||||
params | array<object> | |||||||
2 fields of | ||||||||
keyrequired | string | |
valuerequired | string |
requestDelayMsfilePathrequiredloadedrequiredErrors 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 "http://127.0.0.1:7385/files/agent/providers/anthropic/credentials?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Attach a provider to an agent file
/files/agent/providersA file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · ProviderAttachBody · required
| Field | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
providerrequired | object | A provider carried in the agent's own config. Its API key is a credential (PUT …/providers/{providerId}/credential), never part of this object. | |||||||||||||||||||||||||||||||||
8 fields of | |||||||||||||||||||||||||||||||||||
idrequired | string |
| ||||||
typerequired | string | |||||||
namerequired | string | |||||||
baseUrlrequired | string | |||||||
preset | string | |||||||
defaultModel | string | |||||||
params | array<object> | |||||||
2 fields of | ||||||||
keyrequired | string | |
valuerequired | string |
requestDelayMsResponses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Attached | object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paramsarray<object> | 2 fields of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
keyrequired | string | |
valuerequired | string |
provider_paramsinstructionsrequiredcontextrequiredcompact_threshold, max_request_media_files, max_request_media_mb, compaction_model, audit, dynamic_instructions
toolsrequiredTool declarations
5 fields of tools
namerequired | string | |
enabledrequired | boolean | |
visible | boolean | |
restricted | boolean | |
locked | boolean |
triggersrequiredon_startup, on_inbox, on_outbox, on_file_change, on_chat, on_timer, on_tool_call, on_task_create, on_task_complete, on_logs, on_llm_call
3 fields of triggers
enabledrequired | boolean | ||||||||||||||||||||||||||||||||||
targetsrequired | array<TriggerTarget> | ||||||||||||||||||||||||||||||||||
11 fields of | |||||||||||||||||||||||||||||||||||
scoperequired | string | |
lambda | string | System scope: |
command | string | System scope: shell command (alternative to lambda) |
warm | boolean | |
filter | object | |
debounce_ms | integer | |
interval_ms | integer | |
batch_ms | integer | |
batch_count | integer | |
locked | boolean | |
loop | string | Cognition loop this target wakes; absent = main |
lockedsecurityrequiredlimitsrequiredmessagingrequiredmode (proactive | respond_only | listen_only), receive, network, …
mcp2 fields of mcp
serversrequired | array<McpServerConfig> | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
20 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | ||||||||||
transportrequired | string | ||||||||||
command | string | ||||||||||
args | array<string> | ||||||||||
url | string | ||||||||||
oauth | boolean | ||||||||||
headers | map<string, string> | ||||||||||
header_env | array<object> | ||||||||||
bearer_token_env_var | string | ||||||||||
env | map<string, string> | ||||||||||
env_keys | array<string> | ||||||||||
env_schema | array<object> | ||||||||||
npm_package | string | ||||||||||
pypi_package | string | ||||||||||
source | string | ||||||||||
available_tools | array<object> | ||||||||||
tool_call_timeout_ms | integer | ||||||||||
restricted | boolean | ||||||||||
run_location | string | ||||||||||
credential_files | array<object> | ||||||||||
3 fields of | |||||||||||
pathrequired | string | |
required | boolean | |
write_back | boolean |
new_tools_restrictedadaptersChannel adapters by type
4 fields of adapters
enabledrequired | boolean | ||||
config | object | Adapter-specific settings (no secrets: tokens are credentials) | |||
policy | object | ||||
limits | object | ||||
1 field of | |||||
max_attachment_size | integer | Bytes |
providers8 fields of providers
idrequired | string |
| ||||||
typerequired | string | |||||||
namerequired | string | |||||||
baseUrlrequired | string | |||||||
preset | string | |||||||
defaultModel | string | |||||||
params | array<object> | |||||||
2 fields of | ||||||||
keyrequired | string | |
valuerequired | string |
requestDelayMsloopsInner (side) loops; main is implicit
8 fields of loops
namerequired | string | |
goalrequired | string | Becomes the loop's instructions |
enabledrequired | boolean | |
autostart | boolean | |
autonomous | boolean | |
model | object | |
compact_threshold | integer | null | |
tools | array<string> | Absolute allow-list, intersected with the host's enabled tools |
ws_connectionsservinglocked_fieldsmetadatarequiredcreated_at, updated_at, author, tags, version
filePathrequiredloadedrequiredErrors 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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/agent/providers?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"provider": {
"id": "custom:ab12cd",
"type": "openai-compatible",
"name": "Local LLM",
"baseUrl": "http://127.0.0.1:11434/v1"
}
}'Detach a provider from an agent file
/files/agent/providers/{providerId}Also deletes its stored credentials. A file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Path parameters
| Name | Type | Description |
|---|---|---|
providerIdrequired | string | Provider id in the agent config |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Detached | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/files/agent/providers/anthropic?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"MCP credential metadata of an agent file
/files/agent/mcp/credentialsMetadata only, never the value. A file that is not loaded is read through one readonly connection (nothing written; sealed values read as locked).
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
npmPackagerequired | string |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Metadata | object | |||||||||||||||||||||||||||||||||||||||
filePathrequiredstring | loadedrequiredboolean | | |||||||||||||||||||||||||||||||||||||||
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 "http://127.0.0.1:7385/files/agent/mcp/credentials?path=/home/me/agents/agent-1.adf&npmPackage=NPM_PACKAGE" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Store an MCP credential in an agent file
/files/agent/mcp/credentialsPUT /agents/{id}/mcp/credentials by file path; works on a file that is not loaded. A file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · McpCredentialBody · required
| Field | Type | Description |
|---|---|---|
npmPackagerequired | string | Package or server name the credential belongs to |
envKeyrequired | string | |
valuerequired | string | |
replace | boolean | Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs ( |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Stored | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (credentials_locked): unlock the owner identity, or retry with replace: true. A legacy agent locked with a whole-file password answers 409 credentials_locked until POST /agents/{id}/identity/password/unlock. An envelope refusal also names purpose, sealed (a value is stored sealed here: a replace discards it unread) and envelopeState (locked or foreign); choose on these, not on the message. | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/files/agent/mcp/credentials?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"npmPackage": "@acme/mcp-server",
"envKey": "ACME_TOKEN",
"value": "…"
}'Attach an MCP server to an agent file
/files/agent/mcp/serversA file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · McpAttachBody · required
server (alias serverConfig) with name and transport.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
serverrequired | object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
20 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | ||||||||||
transportrequired | string | ||||||||||
command | string | ||||||||||
args | array<string> | ||||||||||
url | string | ||||||||||
oauth | boolean | ||||||||||
headers | map<string, string> | ||||||||||
header_env | array<object> | ||||||||||
bearer_token_env_var | string | ||||||||||
env | map<string, string> | ||||||||||
env_keys | array<string> | ||||||||||
env_schema | array<object> | ||||||||||
npm_package | string | ||||||||||
pypi_package | string | ||||||||||
source | string | ||||||||||
available_tools | array<object> | ||||||||||
tool_call_timeout_ms | integer | ||||||||||
restricted | boolean | ||||||||||
run_location | string | ||||||||||
credential_files | array<object> | ||||||||||
3 fields of | |||||||||||
pathrequired | string | |
required | boolean | |
write_back | boolean |
serverConfigResponses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Attached | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/agent/mcp/servers?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"server": {
"name": "filesystem",
"transport": "stdio",
"npm_package": "@modelcontextprotocol/server-filesystem"
}
}'Detach an MCP server from an agent file
/files/agent/mcp/servers/{serverName}Also deletes its credentials (mcp:{credentialNamespace}:*, default the server name). A file that is not loaded is refused with 409 agent_leased while another runtime runs it. Credentials are matched by exact prefix.
Path parameters
| Name | Type | Description |
|---|---|---|
serverNamerequired | string | MCP server name in the agent config |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
credentialNamespace | string |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Detached | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/files/agent/mcp/servers/filesystem?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Adapter credential metadata of an agent file
/files/agent/adapters/credentialsMetadata only, never the value. A file that is not loaded is read through one readonly connection (nothing written; sealed values read as locked).
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
adapterTyperequired | string |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Metadata | object | |||||||||||||||||||||||||||||||||||||||
filePathrequiredstring | loadedrequiredboolean | | |||||||||||||||||||||||||||||||||||||||
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 "http://127.0.0.1:7385/files/agent/adapters/credentials?path=/home/me/agents/agent-1.adf&adapterType=ADAPTER_TYPE" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Store an adapter credential in an agent file
/files/agent/adapters/credentialsA file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · AdapterCredentialBody · required
| Field | Type | Description |
|---|---|---|
adapterTyperequired | string | |
envKeyrequired | string | |
valuerequired | string | |
replace | boolean | Owner override while the agent's credentials envelope is locked on this daemon: a locked sealed value is discarded unread and the new value is stored plain, sealed again on unlock; logged to adf_logs ( |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Stored | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | Bad value (key material cannot be replaced over the API), or the agent's credentials envelope is locked on this daemon (credentials_locked): unlock the owner identity, or retry with replace: true. A legacy agent locked with a whole-file password answers 409 credentials_locked until POST /agents/{id}/identity/password/unlock. An envelope refusal also names purpose, sealed (a value is stored sealed here: a replace discards it unread) and envelopeState (locked or foreign); choose on these, not on the message. | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/files/agent/adapters/credentials?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"adapterType": "telegram",
"envKey": "TELEGRAM_BOT_TOKEN",
"value": "…"
}'Attach a channel adapter to an agent file
/files/agent/adaptersA file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Request bodyapplication/json · AdapterAttachBody · required
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
adapterTyperequired | string | |||||||||||||||||||
configrequired | object | |||||||||||||||||||
4 fields of | ||||||||||||||||||||
enabledrequired | boolean | ||||
config | object | Adapter-specific settings (no secrets: tokens are credentials) | |||
policy | object | ||||
limits | object | ||||
1 field of | |||||
max_attachment_size | integer | Bytes |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Attached | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/files/agent/adapters?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"adapterType":"telegram","config":{"enabled":true}}'Detach a channel adapter from an agent file
/files/agent/adapters/{adapterType}Also deletes its credentials. A file that is not loaded is refused with 409 agent_leased while another runtime runs it.
Path parameters
| Name | Type | Description |
|---|---|---|
adapterTyperequired | string | Adapter type, e.g. |
Query parameters
| Name | Type | Description |
|---|---|---|
pathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Detached | object | |||||||||||||||||||||
| |||||||||||||||||||||||
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 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/files/agent/adapters/telegram?path=/home/me/agents/agent-1.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Create a folder for a daemon-side picker
/fs/foldersCreates one folder named name in parent. The parent (after resolving links) must be inside a browse root, as for GET /fs/browse; name is one path segment (no separators, not . or .., no characters Windows refuses, no device name, at most 255 characters). An existing name is refused, never reused. 400 bad_request / invalid_name / not_a_directory, 403 outside_roots, 404 not_found, 409 exists.
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
parentrequired | string | Absolute folder path |
namerequired | string |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 201 | Created | object | |||
| |||||
Errors 400 · 401 · 403 · 404 · 409
| 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 parent is outside the browse roots (outside_roots). | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The resource is in a state that does not allow this now |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/fs/folders" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"parent":"/srv/agents","name":"research"}'{
"path": "/srv/agents/research"
}