On this page

This OpenAPI document

GET/openapi.json

Operation getOpenApiSpecAuthBearer token

Responses

StatusDescriptionBody
200OpenAPI 3.1 documentOpenApiDocument
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/openapi.json" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Stop the daemon gracefully (loopback only)

POST/daemon/shutdown

Operation shutdownDaemonAuthBearer tokenLoopback only

Answers 202 first, then runs the same bounded shutdown as Ctrl+C / SIGTERM: the HTTP server closes (3 s deadline), every agent is unloaded in immediate mode (running turns are cut, no 5 s grace) under a per-agent deadline (10 s, ADF_SHUTDOWN_TIMEOUT_MS), compute containers stop, and the process exits; the whole shutdown is capped at 20 s. adf daemon stop uses it; on Windows it is the only graceful way to stop a detached daemon. Local callers only (see Local-only routes: never through a proxy). No body.

Header parameters

NameTypeDescription
X-ADF-Local-Proofstring

Required only when the daemon runs with ADF_DAEMON_BEHIND_PROXY: the contents of <settings dir>/daemon-local-proof (daemon-local-proof-<port> off the default port) on the daemon host (the adf CLI and terminal app send it automatically to their own daemon).

Responses

StatusDescriptionBody
202Accepted; the daemon exits shortlyShutdownAccepted
acceptedrequiredboolean

Value true

pidrequiredinteger

Daemon process id

Errors 401 · 403 · 405
401Missing or wrong bearer token (unauthorized)
403Not a local caller (loopback_only): the request came from another machine, through a proxy (forwarded headers), or: with ADF_DAEMON_BEHIND_PROXY, without this machine's X-ADF-Local-Proof. Owner secrets and shutdown are handled on the daemon host only. Or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)loopback_onlyhost_not_allowedcross_origin
405Shutdown is not available on this daemon

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/daemon/shutdown" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 202
{
  "accepted": true,
  "pid": 41230
}

Identify this daemon run

GET/version

Operation getVersionAuthBearer token

What a client needs before it attaches to a running daemon: the build version, the internal client API version (clientApiVersion; ADF Studio refuses to attach on a different number, the terminal app on one outside the range it reads), the settings file and data directory it runs on, the mesh runtimeId, its pid, and who launched it (startedBy: studio when ADF Studio spawned it, cli for adf daemon / adf daemon start, service for a service manager). ADF Studio stops only a daemon that reports startedBy: studio. startedBy comes from ADF_DAEMON_STARTED_BY at launch; unset means cli.

Responses

StatusDescriptionBody
200This daemon runDaemonVersionInfo
versionrequiredstring

Build version (package version; dev when run from sources outside npm)

clientApiVersionrequiredinteger

Version of the internal client API (/client/* and its frames). 2 since executor frames carry turn ids and the turn frame exists. ADF Studio needs exactly its own number; the terminal app reads 1 and 2.

settingsPathrequiredstring | null

Settings file this daemon reads and writes; null for an in-memory store

dataDirrequiredstring | null

Directory of the settings file: access token, pid file, logs, runtime keys

runtimeIdrequiredstring | null

Mesh runtime id from settings; null until one was minted

pidrequiredinteger

Daemon process id

startedByrequiredstring

Who launched this daemon run (ADF_DAEMON_STARTED_BY)

One of studio, cli, service

trustobject

K12: whether the owner trusts this daemon's key (trustedDaemonEncKeys). not-applicable: the daemon reads the OS keychain and shares ADF Studio's runtime identity instead.

3 fields of trust · DaemonTrustStatus
staterequiredstring

One of trusted, not-trusted, not-applicable

labelrequiredstring | null

Slot label daemon:<fingerprint> of the daemon key; null without a key file.

messagerequiredstring
localProofobject

Whether this run has a local proof (X-ADF-Local-Proof). Without one, every route that needs it refuses (POST /identity/import, the stored-value reveal routes); on Windows that happens when icacls cannot restrict the proof file. Absent in daemons before this field.

2 fields of localProof
availablerequiredboolean
problemrequiredstring | null

Why there is no proof; null when available.

keychainProblemstring | null

Set when this machine has an OS keychain (Windows, macOS) that the daemon could not read at start (three tries over 5 s), so it runs on its passphrase file: why, and what to do (restart the daemon once the keychain works). Owner create, restore, import and trust-daemon answer 409 keychain_unavailable meanwhile. Null otherwise; absent without an owner identity service or in older daemons.

Errors 401
401Missing or wrong bearer token (unauthorized)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/version" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "version": "0.7.8",
  "clientApiVersion": 2,
  "settingsPath": "/Users/me/Library/Application Support/ADF Studio/adf-settings.json",
  "dataDir": "/Users/me/Library/Application Support/ADF Studio",
  "runtimeId": "V1StGXR8_Z5jdHi6B-myT",
  "pid": 41230,
  "startedBy": "studio"
}