On this page

Resolve an agent file path to its agent id

GET/files/agent

Operation describeAgentFileAuthBearer token

The 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200The filePathAgentInfo
filePathrequiredstring

Canonical path

agentIdrequiredstring | null

config.id; null for an unreadable file

namerequiredstring
loadedrequiredboolean
trackedrequiredboolean

Under a tracked folder

pendingNamestring

A rename waiting for the running agent to stop

reviewedboolean

Not loaded: the agent's id is in reviewedAgents (Studio's background-start review gate)

passwordProtectedboolean

Not loaded: the file has a legacy whole-file password (Studio's background-start password gate)

errorstring

Why the file could not be read

Errors 400 · 401 · 403 · 404
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
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

GET/files/agent/config

Operation getAgentFileConfigAuthBearer token

The 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200The configAgentFileConfigResponse
filePathrequiredstring

Canonical path

agentIdrequiredstring | null
loadedrequiredboolean

Running here or an open document: the live config

configrequiredobject

The agent's AgentConfig

Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/files/agents-folder

Operation getAgentsFolderAuthBearer token

settings.agentsFolder (ignored when it points into the OS temp folder), else <Documents>/adf-agents. Needs no owner identity. Not created by this call.

Responses

StatusDescriptionBody
200The agents folderAgentsFolderInfo
pathrequiredstring
sourcerequiredstring

setting: settings.agentsFolder; default: <Documents>/adf-agents, with Documents resolved as Electron does (the Windows shell folder, XDG_DOCUMENTS_DIR on Linux)

One of setting, default

existsrequiredboolean
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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

Request
curl "http://127.0.0.1:7385/files/agents-folder" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Delete an agent file

DELETE/files

Operation deleteAgentFileAuthBearer token

As 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200DeletedFileDeleteResult
successrequiredboolean

Value true

filePathrequiredstring
stoppedrequiredboolean

The agent was loaded here and was stopped first

agentIdstring
Errors 400 · 401 · 403 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
409The file is in use by another process
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/rename

Operation renameAgentFileOnDiskAuthBearer token

A 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

FieldTypeDescription
pathrequiredstring
newNamerequiredstring

File name without .adf; no path separators

Responses

StatusDescriptionBody
200Renamed or deferredAgentFileRenameResult
successrequiredboolean

Value true

filePathrequiredstring

The new path, or the current one while the rename is deferred

renameDeferredrequiredboolean

The agent runs: its name changed now, the file moves when it stops

agentIdstring
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/clone

Operation cloneAgentFileAuthBearer token

Copies 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

FieldTypeDescription
pathrequiredstring
selectedTablesrequiredarray<string>

Tables to keep (GET /files/agent/tables); without adf_identity the clone gets a fresh identity

Responses

StatusDescriptionBody
201ClonedAgentFileCloneResult
successrequiredboolean

Value true

filePathrequiredstring
namerequiredstring
agentIdrequiredstring

The clone's new config.id

identityrequiredstring

One of fresh, kept

warningsrequiredarray<string>
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/relocate

Operation relocateAgentFileAuthBearer token

The 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

FieldTypeDescription
pathrequiredstring

Absolute path of the .adf file

Responses

StatusDescriptionBody
200Moved, or why notAgentFileRelocateResult
movedTostring

Where the file now is, when it moved

moveErrorstring

Why it did not move, or what is left to clean up

Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/save-as

Operation saveAgentFileAsAuthBearer token

Studio'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

FieldTypeDescription
pathrequiredstring
destPathrequiredstring

Absolute .adf path on the daemon host; its folder must exist

modestring

Only share: the identity-free copy (signing keys, attestations and DID removed; credentials kept only behind a share password). A full copy would keep the agent's config.id and DID and pass review as the original; download one with GET /agents/{id}/export instead.

One of sharedefault: "share"

overwriteboolean

default: false

Responses

StatusDescriptionBody
200WrittenAgentFileSaveAsResult
successrequiredboolean

Value true

filePathrequiredstring
sizerequiredinteger
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/files/snapshot

Operation getAgentFileSnapshotAuthBearer token

share (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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

modestring

One of share, exportdefault: "share"

includeSecretsboolean

mode=export only: keep the plain secrets (a legacy agent's plain signing key, plain credential values) in the copy. 400 with mode=share.

default: false

Header parameters

NameTypeDescription
X-ADF-Local-Proofstring

Required for mode=export, in every mode: the contents of <settings dir>/daemon-local-proof on the daemon host.

Responses

StatusDescriptionBody
200The filestring
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/agents/{id}/export

Operation exportAgentAuthBearer token

A 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
includeSecretsboolean

Keep the plain secrets (a legacy agent's plain signing key, plain credential values) in the copy.

default: false

Header parameters

NameTypeDescription
X-ADF-Local-Proofrequiredstring

The contents of <settings dir>/daemon-local-proof on the daemon host, in every mode.

Responses

StatusDescriptionBody
200The filestring
Errors 401 · 403 · 404 · 409 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/export" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Upload an .adf into a tracked folder

POST/files/import

Operation importAgentFileAuthBearer token

The 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

NameTypeDescription
directorystring

Target folder (absolute); default the agents folder

namerequiredstring

File name, with or without .adf

uniquestring

One of true, false

Request bodyapplication/octet-stream · string · required

No fields.

Responses

StatusDescriptionBody
201ImportedAgentFileImportResult
successrequiredboolean

Value true

filePathrequiredstring
namerequiredstring
agentIdrequiredstring
reviewedrequiredboolean

Always false: review it (POST /agents/review/accept) before it runs

Value false

sizerequiredinteger
idReassignedobject

The upload's config id or DID matched an agent known here (reviewed, loaded, or a file in a tracked folder): it got a fresh id and its identity was stripped, so it is neither a twin nor covered by that agent's review; claiming it mints a new DID

3 fields of idReassigned
previousIdrequiredstring
reasonrequiredstring

One of reviewed, loaded, tracked

identityStrippedrequiredboolean

Value true

Errors 400 · 401 · 403 · 409 · 413 · 415 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
409The resource is in a state that does not allow this now
413Larger than the import limit
415Not application/octet-stream
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/fs/browse

Operation browseFoldersAuthBearer token

Folders 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

NameTypeDescription
pathstring

Absolute folder path

showHiddenstring

One of true, false

Responses

StatusDescriptionBody
200The folderBrowseResult
pathrequiredstring | null

The listed folder; null for the roots listing

parentrequiredstring | null

Its parent while still inside a root

rootsrequiredarray<BrowseRoot>
2 fields of roots
pathrequiredstring
kindrequiredstring

One of home, tracked, agents, configured

entriesrequiredarray<object>
5 fields of entries
namerequiredstring
pathrequiredstring
kindrequiredstring

One of directory, adf

sizeinteger
mtimeMsnumber
truncatedrequiredboolean

More than 2000 entries; the rest are not listed

Errors 400 · 401 · 403 · 404
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/fs/browse" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Tables of an agent file with row counts

GET/files/agent/tables

Operation listAgentFileTablesAuthBearer token

Every 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200TablesAgentFileTablesResult
filePathrequiredstring
loadedrequiredboolean
tablesrequiredarray<object>
2 fields of tables
namerequiredstring
row_countrequiredinteger
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

PUT/files/agent/model

Operation setAgentFileModelAuthBearer token

The 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · AgentFileModelBody · required

FieldTypeDescription
providerrequiredstring

A provider id configured in settings

model_idrequiredstring

Responses

StatusDescriptionBody
200SetAgentFileModelResult
successrequiredboolean

Value true

filePathrequiredstring
modelrequiredobject
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

PUT/files/agent/providers/{providerId}/credential

Operation setAgentFileProviderCredentialAuthBearer token

PUT /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

NameTypeDescription
providerIdrequiredstring

Provider id in the agent config

example: anthropic

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · IdentityValueBody · required

FieldTypeDescription
valuerequiredstring
replaceboolean

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 (credential_replaced). Without it such a write answers 409 credentials_locked.

Responses

StatusDescriptionBody
200Storedobject
agentIdrequiredstring

Agent id

providerIdrequiredstring
successrequiredboolean

Value true

replacedboolean
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409Bad 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.
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/agent/providers/{providerId}/credential/copy-app-key

Operation copyAppProviderKeyToAgentFileAuthBearer token

Studio'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

NameTypeDescription
providerIdrequiredstring

Provider id in the agent config

example: anthropic

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · object · optional

FieldTypeDescription
replaceboolean

Store it although the credentials envelope is locked here (a locked sealed value is discarded).

Responses

StatusDescriptionBody
200Storedobject
agentIdrequiredstring

Agent id

providerIdrequiredstring
successrequiredboolean

Value true

replacedboolean
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409Bad 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.
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/files/agent/providers/{providerId}/credentials

Operation getAgentFileProviderCredentialsAuthBearer token

Metadata 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

NameTypeDescription
providerIdrequiredstring

Provider id in the agent config

example: anthropic

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200Metadataobject
agentIdrequiredstring

Agent id

providerIdrequiredstring
credentialsrequiredmap<string, CredentialMeta>

By credential key (e.g. apiKey)

7 fields of credentials
purposerequiredstring
presentrequiredboolean
storagerequiredstring | null

One of sealed, plain, password, null

sealedrequiredboolean
lockedrequiredboolean

Stored but not readable in this process

lengthrequiredinteger | null

null for crypto:* purposes and locked values

code_accessrequiredboolean
providerConfigobject
3 fields of providerConfig
defaultModelstring
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
requestDelayMsinteger
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/agent/providers

Operation attachAgentFileProviderAuthBearer token

A file that is not loaded is refused with 409 agent_leased while another runtime runs it.

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · ProviderAttachBody · required

FieldTypeDescription
providerrequiredobject

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 provider · AgentProviderConfig
idrequiredstring

anthropic, openai, … or custom:<id>

typerequiredstring

One of anthropic, openai, openai-compatible, openrouter

namerequiredstring
baseUrlrequiredstring
presetstring
defaultModelstring
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
requestDelayMsinteger

Responses

StatusDescriptionBody
200Attachedobject
agentIdrequiredstring

Agent id

providerIdrequiredstring
successrequiredboolean

Value true

alreadyAttachedrequiredboolean
configrequiredobject

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

25 fields of config · AgentConfig
adf_versionrequiredstring

Value 0.2

idrequiredstring

Agent id (stable, the daemon addresses the agent by it)

namerequiredstring
descriptionrequiredstring
handlestring
iconstring
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

autonomousrequiredboolean
autostartboolean
modelrequiredobject
9 fields of model · ModelConfig
providerrequiredstring

Provider id (app provider or one of the agent's own providers)

model_idrequiredstring
temperaturenumber | null
max_tokensinteger | null
top_pnumber | null
reasoningobject

Provider-agnostic reasoning ("thinking") config

multimodalobject
3 fields of multimodal
imageboolean
audioboolean
videoboolean
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
provider_paramsobject
instructionsrequiredstring
contextrequiredobject

compact_threshold, max_request_media_files, max_request_media_mb, compaction_model, audit, dynamic_instructions

toolsrequiredarray<object>

Tool declarations

5 fields of tools
namerequiredstring
enabledrequiredboolean
visibleboolean
restrictedboolean
lockedboolean
triggersrequiredmap<string, TriggerConfig>

on_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
enabledrequiredboolean
targetsrequiredarray<TriggerTarget>
11 fields of targets
scoperequiredstring

One of agent, system

lambdastring

System scope: path/file.ts:functionName

commandstring

System scope: shell command (alternative to lambda)

warmboolean
filterobject
debounce_msinteger
interval_msinteger
batch_msinteger
batch_countinteger
lockedboolean
loopstring

Cognition loop this target wakes; absent = main

lockedboolean
securityrequiredobject
limitsrequiredobject
messagingrequiredobject

mode (proactive | respond_only | listen_only), receive, network, …

mcpobject
2 fields of mcp
serversrequiredarray<McpServerConfig>
20 fields of servers
namerequiredstring
transportrequiredstring

One of stdio, http

commandstring
argsarray<string>
urlstring
oauthboolean
headersmap<string, string>
header_envarray<object>
bearer_token_env_varstring
envmap<string, string>
env_keysarray<string>
env_schemaarray<object>
npm_packagestring
pypi_packagestring
sourcestring
available_toolsarray<object>
tool_call_timeout_msinteger
restrictedboolean
run_locationstring

One of host, shared

credential_filesarray<object>
3 fields of credential_files
pathrequiredstring
requiredboolean
write_backboolean
new_tools_restrictedboolean
adaptersmap<string, AdapterInstanceConfig>

Channel adapters by type

4 fields of adapters
enabledrequiredboolean
configobject

Adapter-specific settings (no secrets: tokens are credentials)

policyobject
limitsobject
1 field of limits
max_attachment_sizeinteger

Bytes

providersarray<AgentProviderConfig>
8 fields of providers
idrequiredstring

anthropic, openai, … or custom:<id>

typerequiredstring

One of anthropic, openai, openai-compatible, openrouter

namerequiredstring
baseUrlrequiredstring
presetstring
defaultModelstring
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
requestDelayMsinteger
loopsarray<LoopConfig>

Inner (side) loops; main is implicit

8 fields of loops
namerequiredstring

pattern: ^[a-z0-9][a-z0-9_-]{0,31}$

goalrequiredstring

Becomes the loop's instructions

enabledrequiredboolean
autostartboolean
autonomousboolean
modelobject

Fields as in ModelConfig above.

compact_thresholdinteger | null
toolsarray<string>

Absolute allow-list, intersected with the host's enabled tools

ws_connectionsarray<object>
servingobject
locked_fieldsarray<string>
metadatarequiredobject

created_at, updated_at, author, tags, version

filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

DELETE/files/agent/providers/{providerId}

Operation detachAgentFileProviderAuthBearer token

Also deletes its stored credentials. A file that is not loaded is refused with 409 agent_leased while another runtime runs it.

Path parameters

NameTypeDescription
providerIdrequiredstring

Provider id in the agent config

example: anthropic

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200Detachedobject
agentIdrequiredstring

Agent id

providerIdrequiredstring
successrequiredboolean

Value true

deletedCredentialsrequiredinteger
configrequiredobject

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

Fields as in AgentConfig above.

filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/files/agent/mcp/credentials

Operation getAgentFileMcpCredentialsAuthBearer token

Metadata 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

npmPackagerequiredstring

Responses

StatusDescriptionBody
200Metadataobject
agentIdrequiredstring

Agent id

npmPackagerequiredstring
credentialsrequiredmap<string, CredentialMeta>

By env key

7 fields of credentials
purposerequiredstring
presentrequiredboolean
storagerequiredstring | null

One of sealed, plain, password, null

sealedrequiredboolean
lockedrequiredboolean

Stored but not readable in this process

lengthrequiredinteger | null

null for crypto:* purposes and locked values

code_accessrequiredboolean
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

PUT/files/agent/mcp/credentials

Operation setAgentFileMcpCredentialAuthBearer token

PUT /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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · McpCredentialBody · required

FieldTypeDescription
npmPackagerequiredstring

Package or server name the credential belongs to

envKeyrequiredstring
valuerequiredstring
replaceboolean

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 (credential_replaced). Without it such a write answers 409 credentials_locked.

Responses

StatusDescriptionBody
200Storedobject
agentIdrequiredstring

Agent id

npmPackagerequiredstring
envKeyrequiredstring
successrequiredboolean

Value true

replacedboolean
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409Bad 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.
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/agent/mcp/servers

Operation attachAgentFileMcpServerAuthBearer token

A file that is not loaded is refused with 409 agent_leased while another runtime runs it.

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · McpAttachBody · required

server (alias serverConfig) with name and transport.

FieldTypeDescription
serverrequiredobject
20 fields of server · McpServerConfig
namerequiredstring
transportrequiredstring

One of stdio, http

commandstring
argsarray<string>
urlstring
oauthboolean
headersmap<string, string>
header_envarray<object>
bearer_token_env_varstring
envmap<string, string>
env_keysarray<string>
env_schemaarray<object>
npm_packagestring
pypi_packagestring
sourcestring
available_toolsarray<object>
tool_call_timeout_msinteger
restrictedboolean
run_locationstring

One of host, shared

credential_filesarray<object>
3 fields of credential_files
pathrequiredstring
requiredboolean
write_backboolean
serverConfigobject

Fields as in McpServerConfig above.

Responses

StatusDescriptionBody
200Attachedobject
agentIdrequiredstring

Agent id

serverNamerequiredstring
successrequiredboolean

Value true

alreadyAttachedrequiredboolean
configrequiredobject

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

Fields as in AgentConfig above.

filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

DELETE/files/agent/mcp/servers/{serverName}

Operation detachAgentFileMcpServerAuthBearer token

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

NameTypeDescription
serverNamerequiredstring

MCP server name in the agent config

example: filesystem

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

credentialNamespacestring

Responses

StatusDescriptionBody
200Detachedobject
agentIdrequiredstring

Agent id

serverNamerequiredstring
successrequiredboolean

Value true

deletedCredentialsrequiredinteger
configrequiredobject

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

Fields as in AgentConfig above.

filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/files/agent/adapters/credentials

Operation getAgentFileAdapterCredentialsAuthBearer token

Metadata 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

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

adapterTyperequiredstring

Responses

StatusDescriptionBody
200Metadataobject
agentIdrequiredstring

Agent id

adapterTyperequiredstring
credentialsrequiredmap<string, CredentialMeta>

By env key

7 fields of credentials
purposerequiredstring
presentrequiredboolean
storagerequiredstring | null

One of sealed, plain, password, null

sealedrequiredboolean
lockedrequiredboolean

Stored but not readable in this process

lengthrequiredinteger | null

null for crypto:* purposes and locked values

code_accessrequiredboolean
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

PUT/files/agent/adapters/credentials

Operation setAgentFileAdapterCredentialAuthBearer token

A file that is not loaded is refused with 409 agent_leased while another runtime runs it.

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · AdapterCredentialBody · required

FieldTypeDescription
adapterTyperequiredstring
envKeyrequiredstring
valuerequiredstring
replaceboolean

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 (credential_replaced). Without it such a write answers 409 credentials_locked.

Responses

StatusDescriptionBody
200Storedobject
agentIdrequiredstring

Agent id

adapterTyperequiredstring
envKeyrequiredstring
successrequiredboolean

Value true

replacedboolean
filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409Bad 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.
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/files/agent/adapters

Operation attachAgentFileAdapterAuthBearer token

A file that is not loaded is refused with 409 agent_leased while another runtime runs it.

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Request bodyapplication/json · AdapterAttachBody · required

FieldTypeDescription
adapterTyperequiredstring
configrequiredobject
4 fields of config · AdapterInstanceConfig
enabledrequiredboolean
configobject

Adapter-specific settings (no secrets: tokens are credentials)

policyobject
limitsobject
1 field of limits
max_attachment_sizeinteger

Bytes

Responses

StatusDescriptionBody
200Attachedobject
agentIdrequiredstring

Agent id

adapterTyperequiredstring
successrequiredboolean

Value true

alreadyAttachedrequiredboolean
configrequiredobject

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

Fields as in AgentConfig above.

filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

DELETE/files/agent/adapters/{adapterType}

Operation detachAgentFileAdapterAuthBearer token

Also deletes its credentials. A file that is not loaded is refused with 409 agent_leased while another runtime runs it.

Path parameters

NameTypeDescription
adapterTyperequiredstring

Adapter type, e.g. telegram

example: telegram

Query parameters

NameTypeDescription
pathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-1.adf

Responses

StatusDescriptionBody
200Detachedobject
agentIdrequiredstring

Agent id

adapterTyperequiredstring
successrequiredboolean

Value true

deletedCredentialsrequiredinteger
configrequiredobject

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

Fields as in AgentConfig above.

filePathrequiredstring
loadedrequiredboolean
Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/fs/folders

Operation createFolderAuthBearer token

Creates 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

FieldTypeDescription
parentrequiredstring

Absolute folder path

namerequiredstring

Responses

StatusDescriptionBody
201Createdobject
pathrequiredstring
Errors 400 · 401 · 403 · 404 · 409
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The parent is outside the browse roots (outside_roots).
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now

Error bodies use the error format.

Example

Request
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"}'
Response 201
{
  "path": "/srv/agents/research"
}