# x0xd API Reference
Base URL: `http://127.0.0.1:12700` (local dev) or `http://127.0.0.1:12600` (VPS bootstrap nodes).
This is the at-a-glance API map for `x0xd`. The canonical source is the
endpoint registry in [`src/api/mod.rs`](../src/api/mod.rs); both `x0xd` and
the `x0x` CLI consume it so routes and CLI commands stay in lockstep
(`x0x routes` prints them at runtime). For request/response examples and
the WebSocket protocol details, see [api-reference.md](api-reference.md).
The daemon currently exposes **129 endpoints**. Authentication is by bearer
token (`Authorization: Bearer …`). The token is auto-discovered from
`~/.local/share/x0x/api-token` (Linux) or
`~/Library/Application Support/x0x/api-token` (macOS).
## System
| GET | `/health` | `x0x health` | Health probe |
| GET | `/status` | `x0x status` | Runtime status with uptime |
| POST | `/shutdown` | `x0x stop` | Graceful shutdown |
| GET | `/constitution` | `x0x constitution` | x0x Constitution (Markdown) |
| GET | `/constitution/json` | `x0x constitution --json` | Constitution + version metadata (JSON) |
## Identity
| GET | `/agent` | `x0x agent` | Local agent identity |
| POST | `/announce` | `x0x announce` | Re-announce identity to network |
| GET | `/agent/user-id` | `x0x agent user-id` | Configured user ID (if any) |
| GET | `/agent/card` | `x0x agent card` | Shareable identity card |
| GET | `/introduction` | `x0x agent introduction` | Trust-scoped introduction card |
| POST | `/agent/card/import` | `x0x agent import` | Import identity card into contacts |
## Network and diagnostics
| GET | `/peers` | `x0x peers` | Connected gossip peers |
| GET | `/network/status` | `x0x network status` | NAT / connectivity diagnostics |
| GET | `/network/bootstrap-cache` | `x0x network cache` | Bootstrap cache stats |
| GET | `/diagnostics/connectivity` | `x0x diagnostics connectivity` | ant-quic NodeStatus (UPnP / NAT / relay / mDNS) |
| GET | `/diagnostics/gossip` | `x0x diagnostics gossip` | PubSub drop-detection counters |
| GET | `/diagnostics/dm` | `x0x diagnostics dm` | DM send/receive counters and per-peer health |
| GET | `/diagnostics/groups` | `x0x diagnostics groups` | Per-group ingest counters and drop buckets |
| GET | `/diagnostics/exec` | `x0x diagnostics exec` | Remote-exec counters, warnings, ACL summary |
| POST | `/peers/:peer_id/probe` | `x0x peer probe` | Active liveness + RTT probe (ant-quic) |
| GET | `/peers/:peer_id/health` | `x0x peer health` | Connection health snapshot |
| GET | `/peers/events` | `x0x peer events` | SSE peer-lifecycle events (Established/Replaced/Closing/Closed) |
## Presence
| GET | `/presence` | `x0x presence` | Online agents (alias for `/presence/online`) |
| GET | `/presence/online` | `x0x presence online` | All currently online agents (network view, non-blocked) |
| GET | `/presence/foaf` | `x0x presence foaf` | FOAF random-walk discovery |
| GET | `/presence/find/:id` | `x0x presence find` | Find a specific agent by ID via FOAF walk |
| GET | `/presence/status/:id` | `x0x presence status` | Local cache presence status for an agent |
| GET | `/presence/events` | `x0x presence events` | SSE presence online/offline stream |
## Gossip messaging
| POST | `/publish` | `x0x publish` | Publish to a topic |
| POST | `/subscribe` | `x0x subscribe` | Subscribe to a topic |
| DELETE | `/subscribe/:id` | `x0x unsubscribe` | Unsubscribe |
| GET | `/events` | `x0x events` | SSE message stream |
## Agent / machine discovery
| GET | `/agents/discovered` | `x0x agents list` | List discovered agents |
| GET | `/agents/discovered/:agent_id` | `x0x agents get` | Discovered-agent details |
| GET | `/agents/:agent_id/machine` | `x0x agents machine` | Resolve agent → current machine endpoint |
| POST | `/agents/find/:agent_id` | `x0x agents find` | Actively look up an agent |
| GET | `/agents/reachability/:agent_id` | `x0x agents reachability` | Reachability heuristics |
| GET | `/users/:user_id/agents` | `x0x agents by-user` | Agents linked to a user |
| GET | `/machines/discovered` | `x0x machines discovered` | Discovered machine endpoints |
| GET | `/machines/discovered/:machine_id` | `x0x machines get` | Discovered-machine details |
| GET | `/users/:user_id/machines` | `x0x machines by-user` | Machine endpoints by user ID |
## Contacts
| GET | `/contacts` | `x0x contacts list` | List contacts |
| POST | `/contacts` | `x0x contacts add` | Add contact |
| POST | `/contacts/trust` | `x0x trust set` | Quick trust update |
| PATCH | `/contacts/:agent_id` | `x0x contacts update` | Update contact |
| DELETE | `/contacts/:agent_id` | `x0x contacts remove` | Remove contact |
| POST | `/contacts/:agent_id/revoke` | `x0x contacts revoke` | Revoke contact |
| GET | `/contacts/:agent_id/revocations` | `x0x contacts revocations` | List revocations |
## Machine pinning (per contact)
| GET | `/contacts/:agent_id/machines` | `x0x machines list` | List a contact's machines |
| POST | `/contacts/:agent_id/machines` | `x0x machines add` | Add machine record |
| DELETE | `/contacts/:agent_id/machines/:machine_id` | `x0x machines remove` | Remove machine record |
| POST | `/contacts/:agent_id/machines/:machine_id/pin` | `x0x machines pin` | Pin machine |
| DELETE | `/contacts/:agent_id/machines/:machine_id/pin` | `x0x machines unpin` | Unpin machine |
## Trust evaluation
| POST | `/trust/evaluate` | `x0x trust evaluate` | Evaluate `(agent_id, machine_id)` against the contact store |
## Direct messaging
| POST | `/agents/connect` | `x0x direct connect` | Connect to an agent (peer-ID hole-punching) |
| POST | `/machines/connect` | `x0x machines connect` | Connect directly to a machine endpoint |
| POST | `/direct/send` | `x0x direct send` | Send a direct message |
| GET | `/direct/connections` | `x0x direct connections` | List direct connections |
| GET | `/direct/events` | `x0x direct events` | SSE direct-message stream |
## Remote exec (Tier-1, allowlisted)
Disabled unless an exec ACL is loaded with `[exec].enabled = true`. See
[exec.md](exec.md) and [design/x0x-exec.md](design/x0x-exec.md).
| POST | `/exec/run` | `x0x exec` | Run an allowlisted non-interactive command on a remote daemon |
| POST | `/exec/cancel` | `x0x exec cancel` | Cancel an in-flight exec request |
| GET | `/exec/sessions` | `x0x exec sessions` | List local pending and remote active sessions |
## MLS-encrypted groups
| POST | `/mls/groups` | `x0x groups create` | Create encrypted group |
| GET | `/mls/groups` | `x0x groups list` | List encrypted groups |
| GET | `/mls/groups/:id` | `x0x groups get` | Group details |
| POST | `/mls/groups/:id/members` | `x0x groups add-member` | Add member |
| DELETE | `/mls/groups/:id/members/:agent_id` | `x0x groups remove-member` | Remove member |
| POST | `/mls/groups/:id/encrypt` | `x0x groups encrypt` | Encrypt payload |
| POST | `/mls/groups/:id/decrypt` | `x0x groups decrypt` | Decrypt payload |
| POST | `/mls/groups/:id/welcome` | `x0x groups welcome` | Create welcome for new member |
## Named groups — core
| POST | `/groups` | `x0x group create` | Create named group |
| GET | `/groups` | `x0x group list` | List groups |
| GET | `/groups/:id` | `x0x group info` | Group info |
| PATCH | `/groups/:id` | `x0x group update` | Update name/description (admin+) |
| DELETE | `/groups/:id` | `x0x group leave` | Leave or delete group |
| GET | `/groups/:id/members` | `x0x group members` | List members |
| POST | `/groups/:id/members` | `x0x group add-member` | Add member (creator-authored) |
| DELETE | `/groups/:id/members/:agent_id` | `x0x group remove-member` | Remove member (creator-authored) |
| POST | `/groups/:id/invite` | `x0x group invite` | Generate invite link |
| POST | `/groups/join` | `x0x group join` | Join from invite |
| PUT | `/groups/:id/display-name` | `x0x group set-name` | Set display name |
## Named groups — public messaging (Phase E)
| POST | `/groups/:id/send` | `x0x group send` | Publish a signed message to a `SignedPublic` group |
| GET | `/groups/:id/messages` | `x0x group messages` | Retrieve cached public-group messages |
## Named groups — policy, roles, ban, requests
| PATCH | `/groups/:id/policy` | `x0x group policy` | Update group policy (owner only) |
| PATCH | `/groups/:id/members/:agent_id/role` | `x0x group set-role` | Change a member's role (admin+) |
| POST | `/groups/:id/ban/:agent_id` | `x0x group ban` | Ban a member (admin+) |
| DELETE | `/groups/:id/ban/:agent_id` | `x0x group unban` | Unban a member (admin+) |
| GET | `/groups/:id/requests` | `x0x group requests` | List join requests (admin+) |
| POST | `/groups/:id/requests` | `x0x group request-access` | Submit a join request |
| POST | `/groups/:id/requests/:request_id/approve` | `x0x group approve-request` | Approve join request (admin+) |
| POST | `/groups/:id/requests/:request_id/reject` | `x0x group reject-request` | Reject join request (admin+) |
| DELETE | `/groups/:id/requests/:request_id` | `x0x group cancel-request` | Cancel own pending request |
## Named groups — state-commit chain (Phase D.3)
| GET | `/groups/:id/state` | `x0x group state` | Inspect signed state-commit chain |
| POST | `/groups/:id/state/seal` | `x0x group state-seal` | Advance commit chain + republish signed card |
| POST | `/groups/:id/state/withdraw` | `x0x group state-withdraw` | Seal a terminal withdrawal |
## Named groups — discovery (Phase C.2)
| GET | `/groups/discover` | `x0x group discover` | List locally known discoverable groups |
| GET | `/groups/discover/nearby` | `x0x group discover-nearby` | Presence-social browse (PublicDirectory) |
| GET | `/groups/discover/subscriptions` | `x0x group discover-subscriptions` | List active shard subscriptions |
| POST | `/groups/discover/subscribe` | `x0x group discover-subscribe` | Subscribe to a tag/name/id directory shard |
| DELETE | `/groups/discover/subscribe/:kind/:shard` | `x0x group discover-unsubscribe` | Unsubscribe from a shard |
| GET | `/groups/cards/:id` | `x0x group card` | Fetch a single group card |
| POST | `/groups/cards/import` | `x0x group card-import` | Import a group card into local cache |
## Named groups — shared-secret encryption (Phase D.2)
| POST | `/groups/:id/secure/encrypt` | `x0x group secure-encrypt` | Encrypt with the group shared secret (member-only) |
| POST | `/groups/:id/secure/decrypt` | `x0x group secure-decrypt` | Decrypt with the group shared secret (member-only) |
| POST | `/groups/:id/secure/reseal` | `x0x group secure-reseal` | Re-seal current shared secret to a recipient |
| POST | `/groups/secure/open-envelope` | `x0x group secure-open-envelope` | Open a `SecureShareDelivered` envelope (adversarial test) |
## Task lists (CRDTs)
| GET | `/task-lists` | `x0x tasks list` | List task lists |
| POST | `/task-lists` | `x0x tasks create` | Create task list |
| GET | `/task-lists/:id/tasks` | `x0x tasks show` | Show tasks |
| POST | `/task-lists/:id/tasks` | `x0x tasks add` | Add task |
| PATCH | `/task-lists/:id/tasks/:tid` | `x0x tasks claim` / `x0x tasks complete` | Claim or complete (`action: claim\|complete`) |
## Key-value stores
| GET | `/stores` | `x0x store list` | List stores |
| POST | `/stores` | `x0x store create` | Create store |
| POST | `/stores/:id/join` | `x0x store join` | Join existing store |
| GET | `/stores/:id/keys` | `x0x store keys` | List keys |
| PUT | `/stores/:id/:key` | `x0x store put` | Put value |
| GET | `/stores/:id/:key` | `x0x store get` | Get value |
| DELETE | `/stores/:id/:key` | `x0x store rm` | Remove value |
## File transfers
| POST | `/files/send` | `x0x send-file` | Start outgoing transfer |
| GET | `/files/transfers` | `x0x transfers` | List transfers |
| GET | `/files/transfers/:id` | `x0x transfer-status` | Inspect one transfer |
| POST | `/files/accept/:id` | `x0x accept-file` | Accept incoming transfer |
| POST | `/files/reject/:id` | `x0x reject-file` | Reject incoming transfer |
## Self-update
| GET | `/upgrade` | `x0x upgrade` | Check for updates |
| POST | `/upgrade/apply` | `x0x upgrade --apply` | Apply latest verified release manifest |
## WebSocket and GUI
| GET | `/ws` | — | General-purpose WebSocket |
| GET | `/ws/direct` | — | WebSocket session for direct messaging |
| GET | `/ws/sessions` | `x0x ws sessions` | List WebSocket sessions |
| GET | `/gui` | `x0x gui` | Embedded HTML GUI |
## Notes
- Success responses are usually flattened: `{"ok":true,...}`.
- Error responses use: `{"ok":false,"error":"..."}`.
- `x0x routes` prints the live registry — use it whenever this doc and the
daemon disagree (the registry wins).
- For request/response examples and the WebSocket message schema, see
[api-reference.md](api-reference.md).