REST API

Base URL

http://localhost:9090/api

All endpoints require the brain to be running (feral start). Responses are JSON.

Dashboard

Method	Path	Description
`GET`	`/api/dashboard/status`	Brain status, uptime, connected devices
`GET`	`/api/dashboard/context`	Current context window (health, scene, calendar)
`GET`	`/api/dashboard/timeline`	Recent events and conversations
`POST`	`/api/dashboard/command`	Send a text command to the brain

Example: Send a command

curl -X POST http://localhost:9090/api/dashboard/command \
  -H "Content-Type: application/json" \
  -d '{ "text": "What is my heart rate?" }'

{
  "response": "Your heart rate is 72 bpm, measured 3 seconds ago from your wristband.",
  "sdui": null,
  "sources": ["wristband_a3f2"]
}

Skills

Method	Path	Description
`GET`	`/api/skills`	List all registered skills
`GET`	`/api/skills/:id`	Get skill manifest and status
`POST`	`/api/skills/:id/execute`	Manually trigger a skill
`POST`	`/api/skills/install`	Install a skill from URL or local path
`DELETE`	`/api/skills/:id`	Uninstall a skill

Example: List skills

curl http://localhost:9090/api/skills

{
  "skills": [
    { "id": "weather", "name": "Weather", "version": "1.2.0", "status": "active" },
    { "id": "calendar", "name": "Google Calendar", "version": "2.0.1", "status": "active" },
    { "id": "smart_home", "name": "Smart Home Control", "version": "1.0.0", "status": "active" }
  ]
}

Memory

Method	Path	Description
`GET`	`/api/memory/episodes`	List episodic memories (paginated)
`GET`	`/api/memory/search`	Semantic search across all memory tiers
`POST`	`/api/memory/note`	Store a note in the knowledge base
`GET`	`/api/memory/knowledge`	Query the knowledge graph
`DELETE`	`/api/memory/episodes/:id`	Delete a specific episode

Example: Semantic search

Runs MemoryStore.search_all: episodes and notes through FTS5 plus vector cosine, knowledge triples, and knowledge-graph entities, merged by score. q and query are both accepted. An empty query is a 400, never an empty result set.

curl "http://localhost:9090/api/memory/search?q=last+time+I+went+running&limit=5"

{
  "query": "last time I went running",
  "count": 2,
  "tiers": { "episode": 1, "note": 1 },
  "degradations": [],
  "degraded": false,
  "results": [
    {
      "tier": "episode",
      "score": 0.94,
      "id": "ep_2026_0410_morning",
      "summary": "Morning 5K run in Prospect Park. Avg HR 145 bpm, pace 5:20/km.",
      "relevance_score": 0.94
    },
    {
      "tier": "note",
      "score": 0.61,
      "id": "n_18f2",
      "content": "New running shoes break in around 40km.",
      "relevance_score": 0.61
    }
  ]
}

degradations is the point of the payload as much as results. Each tier is isolated, so one that raises does not take out the three that answered; the failure is named here instead of silently shrinking the result set. A caller must not read count: 0 as “the store knows nothing” while degraded is true. /internal/memory/search remains as the notes-only legacy surface and also accepts either spelling of the query parameter.

Identity

Method	Path	Description
`GET`	`/api/identity/user`	Get current USER.md content
`PUT`	`/api/identity/user`	Update USER.md
`GET`	`/api/identity/soul`	Get SOUL.md (system persona)
`GET`	`/api/identity/twin`	Query the digital twin
`POST`	`/api/identity/twin/ask`	Ask the digital twin a question

Example: Ask the digital twin

curl -X POST http://localhost:9090/api/identity/twin/ask \
  -H "Content-Type: application/json" \
  -d '{ "question": "Would I enjoy this job offer?" }'

{
  "answer": "Based on your preference for remote work, interest in systems programming, and past dissatisfaction with large-company bureaucracy, this startup role aligns well. However, the on-call rotation conflicts with your sleep optimization goals.",
  "confidence": 0.82
}

Devices & Hardware

Method	Path	Description
`GET`	`/api/devices/connected`	Live daemons (`devices[]`) plus nodes the brain knows about that are not reporting (`offline[]`). Merges `state.daemons` with the session-handoff registry rather than letting either shadow the other. Both lists empty means nothing has ever paired.
`GET`	`/api/devices/paired`	List paired devices (claimed by default; `include_unclaimed=true` optional)
`POST`	`/api/devices/pair`	Mint daemon/browser pairing token
`GET`	`/api/devices/pair/url`	Mint one-time pair URL payload
`GET`	`/api/devices/pair/qr`	Render pair payload as QR image
`GET`	`/api/devices/pair/check`	Check token state (and PIN requirement)
`POST`	`/api/devices/pair/verify_pin`	Verify pairing PIN
`POST`	`/api/devices/pair/complete`	Complete phone/browser pairing
`POST`	`/api/devices/pair/prune`	Revoke unclaimed tokens in bulk
`POST`	`/api/devices/handoff`	Initiate a session handoff between devices
`DELETE`	`/api/devices/{device_id}`	Revoke (un-pair) a device
`GET`	`/api/nodes/health`	All node health status with heartbeat freshness
`GET`	`/api/commands/recent`	Recent commands with full lifecycle state
`GET`	`/api/commands/{command_id}`	Single command detail including state history
`POST`	`/api/proactive/dismiss`	Dismiss a proactive alert (learns from it)

HUP device registry

Method	Path	Description
`GET`	`/api/hardware/devices`	List registered HUP devices and their manifests
`GET`	`/api/hardware/device/{device_id}`	Single device manifest and adapter status
`POST`	`/api/hardware/execute`	Execute a HUP action on a device (`device_id`, `capability_id`, `action_type`, `parameters`, optional `confirmed`)
`GET`	`/api/hardware/context`	LLM-facing hardware context string (capabilities summary)
`GET`	`/api/hardware/stats`	Device registry statistics
`GET`	`/api/hardware/mesh`	Hardware mesh state (connected nodes, announced peripherals). Every `nodes[]` row carries `online: true` — the list only contains nodes holding an open socket, and saying so beats leaving clients to infer it from the row’s presence.
`GET`	`/api/hardware/fleet`	Unified fleet view — full manifests with derived safety tiers, last verification (honesty loop) state, mesh nodes, announced devices, and registry stats. Intended for companion-app device cards without per-device UI code.
`POST`	`/api/hardware/invoke`	Invoke a capability on a mesh node. Body is `{node_id, command, params}`; `{device_id, method, args}` is accepted as a legacy alias. An empty `node_id` or `command` is a 400, not a “Node not connected” naming no node.

GET /api/hardware/device/{device_id} answers 404 for an unknown id and 503 when there is no registry. Both used to be 200 {"error": ...}, which asserts that the body is the device: a client that stores the response as its detail state replaced the row it already had with an error object.

Access Mode & Remote Reachability

Method	Path	Description
`GET`	`/api/access/status`	Current pairing mode + Tailscale/Funnel status
`POST`	`/api/access/remote-up`	Enable remote mode and Tailscale Funnel
`POST`	`/api/access/remote-down`	Disable remote mode and return to localhost mode

Approvals (Execution Inbox)

The approval inbox lets a non-chat client (web UI, CLI, mobile, automation) resolve pending tool-execution approvals without having to type an acknowledgement into a chat session. A pending request is created by the orchestrator whenever enforce_safety() blocks a tool call (see Autonomy Levels).

Method	Path	Description
`GET`	`/api/approvals`	List pending tool-approval requests. Optional query params: `session_id` (filter), `limit` (1–500, default 100).
`POST`	`/api/approvals/{request_id}/approve`	Approve a pending request and execute the tool.
`POST`	`/api/approvals/{request_id}/reject`	Reject a pending request without executing.

Both approve and reject accept an optional JSON body:

{ "session_id": "s-abc123" }

When session_id is provided it must match the session that originated the request, or the call returns 409 session_mismatch.

Example: list pending approvals

curl "http://localhost:9090/api/approvals?session_id=s-abc123&limit=50"

{
  "count": 1,
  "approvals": [
    {
      "request_id": "apr_01HXYZ...",
      "session_id": "s-abc123",
      "tool_name": "browser__navigate",
      "args": { "url": "https://example.com" },
      "safety_level": "privileged",
      "created_at": 1746230412.81,
      "status": "pending"
    }
  ]
}

Example: approve

curl -X POST "http://localhost:9090/api/approvals/apr_01HXYZ.../approve" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "s-abc123" }'

{
  "success": true,
  "status": "approved",
  "request_id": "apr_01HXYZ...",
  "session_id": "s-abc123",
  "tool_name": "browser__navigate",
  "summary": "Navigated to https://example.com",
  "result": { "ok": true }
}

Example: reject

curl -X POST "http://localhost:9090/api/approvals/apr_01HXYZ.../reject" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "s-abc123" }'

{
  "success": true,
  "status": "rejected",
  "request_id": "apr_01HXYZ...",
  "session_id": "s-abc123",
  "tool_name": "browser__navigate"
}

Status codes

Code	Meaning
`200`	Resolved (approved or rejected).
`404`	Unknown `request_id` (already resolved, expired, or never existed).
`409`	`session_mismatch` — supplied `session_id` does not match the pending request.
`503`	Orchestrator or tool runner not initialised yet.

Checkpoints (undo file writes)

Every coding_tools__write_file and coding_tools__edit_file stashes the file’s pre-write bytes in a content-addressed store keyed by turn_id, the id shared by every tool call made while answering one user message. Git is never invoked. See Coding Harness.

Method	Path	Description
`GET`	`/api/checkpoints/turns`	Turns that wrote at least one file, most recent first. Query: `session_id`, `limit` (1 to 200, default 20)
`GET`	`/api/checkpoints/turns/{turn_id}`	Per-write rows for one turn, plus the revert plan. `404` when the turn has no checkpoints
`POST`	`/api/checkpoints/revert`	Revert a turn. Body: `{turn_id?, session_id?, force?, dry_run?}`

Omit turn_id on the revert and the most recent checkpointed turn for session_id is used. 503 when the checkpoint store cannot be opened. Without force, any file whose current content no longer matches what FERAL left there is listed under drifted and the whole revert refuses with success: false. That refusal is the point of the endpoint: a revert that silently discards somebody else’s newer edit is worse than no revert at all.

Every response carries bash_not_covered: true and a note saying so, on success as well as failure. Shell commands are not checkpointed, so anything coding_tools__bash changed in the turn is not reverted. A partial revert that reads as complete is worse than none.

{
  "success": true,
  "turn_id": "turn_9f2c1a77d0e45b13",
  "dry_run": false,
  "forced": false,
  "reverted": ["/repo/src/app.py"],
  "reverted_count": 1,
  "skipped": [],
  "drifted": [],
  "files": [
    { "path": "/repo/src/app.py", "status": "restorable", "action": "restore", "detail": "" }
  ],
  "bash_not_covered": true,
  "note": "Checkpoints cover coding_tools__write_file and coding_tools__edit_file only. ..."
}

feral checkpoints in the CLI deliberately does not go through these routes; it reads the same SQLite index directly, because the case you most need a revert in is the one where the brain is not answering.

Plan Mode

A per-session posture in which the agent researches and proposes but cannot mutate state. These routes live on the session resource and never touch security.autonomy_mode, which is a separate, persisted, global axis. See Plan Mode.

Method	Path	Description
`GET`	`/api/sessions/{session_id}/plan_mode`	Current posture: `plan_mode`, `entered_at`, `reason`, `entered_by`, `plan_count`, `latest_plan`
`POST`	`/api/sessions/{session_id}/plan_mode`	Body `{"enabled": bool, "reason"?: str, "approved"?: bool}`. `400` when `enabled` is missing or not a bool

The exit route hard-codes actor="user": it is reachable by the operator, not by the model, and the orchestrator refuses any other actor. approved is recorded for the UI and confers no privilege; every mutating call in the turns that follow still goes through the session’s autonomy mode.

Autonomy

Method	Path	Description
`GET`	`/api/autonomy`	Current tier, read off the running tool runner
`POST`	`/api/autonomy`	`{"mode": "strict" \| "hybrid" \| "loose"}`. Applies live and persists to `security.autonomy_mode`. Responds `{"success": true, "mode": ..., "persisted": bool}`; `persisted: false` means the disk write failed and the live change was kept anyway

Channels

Method	Path	Description
`GET`	`/api/channels`	List all channel statuses
`GET`	`/api/channels/:name/status`	Status of a specific channel (telegram, slack, etc.)
`POST`	`/api/channels/push/register`	Register a push notification device token
`GET`	`/api/channels/push/devices`	List registered push devices
`DELETE`	`/api/channels/push/devices/:id`	Unregister a push device
`POST`	`/api/channels/push/test`	Send a test push notification

Error Format

All errors follow a consistent shape:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill 'invalid_id' not found.",
    "details": null
  }
}

HTTP Code	Meaning
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid token
`404`	Resource not found
`409`	Conflict — device already paired, skill already installed
`500`	Internal brain error

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Base URL

Dashboard

Example: Send a command

Skills

Example: List skills

Memory

Example: Semantic search

Identity

Example: Ask the digital twin

Devices & Hardware

HUP device registry

Access Mode & Remote Reachability

Approvals (Execution Inbox)

Example: list pending approvals

Example: approve

Example: reject

Status codes

Checkpoints (undo file writes)

Plan Mode

Autonomy

Channels

Error Format

​Base URL

​Dashboard

​Example: Send a command

​Skills

​Example: List skills

​Memory

​Example: Semantic search

​Identity

​Example: Ask the digital twin

​Devices & Hardware

​HUP device registry

​Access Mode & Remote Reachability

​Approvals (Execution Inbox)

​Example: list pending approvals

​Example: approve

​Example: reject

​Status codes

​Checkpoints (undo file writes)

​Plan Mode

​Autonomy

​Channels

​Error Format

Base URL

Dashboard

Example: Send a command

Skills

Example: List skills

Memory

Example: Semantic search

Identity

Example: Ask the digital twin

Devices & Hardware

HUP device registry

Access Mode & Remote Reachability

Approvals (Execution Inbox)

Example: list pending approvals

Example: approve

Example: reject

Status codes

Checkpoints (undo file writes)

Plan Mode

Autonomy

Channels

Error Format