openexec-api

Curl recipes against the FastAPI backend — for hitting HTTP routes, not for inspecting SQLite or tailing logs on a host.

Base URLs

export OE_API=http://localhost:8000   # local (`make dev` must be running) — the default
export OE_API=https://<your-host>     # a deployed environment

All recipes below use $OE_API. If it is unset and the user doesn't specify, assume http://localhost:8000.

Auth

-H "x-api-key: $BACKEND_SHARED_SECRET"

Rules:

• Never expand $BACKEND_SHARED_SECRET into the literal value in commands you print, in PRs, or in commit messages.
• Never write the value to a file. Do not read from .env to "help" — if the env var isn't exported, ask the user to export it before proceeding.
• For routes that vary by caller, optionally add -H "x-caller-email: <user's-own-email>". Never put someone else's email there — the backend uses that header to resolve the caller's Person row and pull their per-person Honcho memory.

• Signed callers. When the API has CALLER_ASSERTION_PUBLIC_KEYS set, a bare x-caller-email is refused (401 caller_assertion_required), and a request with only x-api-key is a service that is never the owner. Owner-only routes refuse it. Then ask the user to export the UI's CALLER_ASSERTION_PRIVATE_KEY and sign each request instead of sending x-caller-email. Treat that key like the shared secret: never expand, print or store it.

  -H "x-caller-assertion: $(uv run --with cryptography python scripts/mint-caller-assertion.py GET /today)"

  Each assertion covers one request: the same method, the exact path and query, within 30 seconds, once. So mint one per call. It signs as the operator (the owner); --email <user's-own-email> signs as that user.

Safety tiers

• Green — auto-run. All GET requests, and the cheap idempotent regenerate POSTs.
• Yellow — confirm once per session. Writes that change durable state but are reversible (e.g. archiving a Person, deleting a scheduled action).
• Red — print the curl, wait for explicit "go," no chaining. POST /fixtures/reset, POST /fixtures/{name}/load, POST /fixtures/unload, POST /fixtures/snapshot, POST /chat (impersonates the user — generally don't invoke from Claude).

Each red command needs its own "go" — a prior approval does not carry over.

Green: health & introspection

curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/health | jq
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/health/honcho | jq

/health/honcho returns one of:

• {"status": "disabled"} — Honcho is off
• {"status": "ok", "latency_ms": ...} — workspace reachable
• {"status": "error", "error_type": "...", "error_msg": "..."} — wrapper or network failure

Green: architecture page

# All sections with freshness
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/architecture/sections | jq '.sections[] | {id, fresh, generated_at}'

# One section
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/architecture/sections/honcho | jq

# Cache key debug (per-component hashes feeding FactsBundle.core_hash)
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/architecture/debug/bundle | jq

Green/Yellow: force regenerate a section

Cheap, idempotent, but it does call Claude and write to disk — treat as yellow (one confirm per session is enough).

curl -sX POST -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/architecture/sections/honcho/regenerate | jq

Replace honcho with any section id from sections.py: overview, lifecycle, agents, caching, rag, review, memory, honcho, org, audit, schemas, workflows, scheduler, integrations, today, api.

Green: today / org / scheduler views

curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/today | jq
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/people | jq
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/people/by-scope/CEO | jq
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" "$OE_API/scheduled_actions?status=pending" | jq

Green: audit log

# Tail recent events
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" "$OE_API/audit/logs?limit=20" | jq

# Filter by event_type (peer_memory rows are Honcho ops)
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" "$OE_API/audit/logs?event_type=peer_memory&limit=10" | jq

# One event by id (returns full details_json)
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" "$OE_API/audit/logs/12345" | jq

Green: fixtures (demo companies)

# List available demos
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/fixtures | jq

# Current load state
curl -s -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/fixtures/status | jq

Red: fixtures (mutating)

Each of these is destructive or significantly state-altering. Print the exact curl, wait for "go," do not chain.

# Snapshot current local state before loading a demo (one-time setup before first demo load)
curl -sX POST -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/fixtures/snapshot

# Load a demo company (wipes current local state, switches Honcho workspace)
curl -sX POST -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/fixtures/<name>/load

# Unload demo (restores the snapshot, deletes the demo Honcho workspace)
curl -sX POST -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/fixtures/unload

# Full factory reset (wipes profile.yaml, company/, ChromaDB, ALL episodic tables,
# people store, departments, Honcho workspace, snapshot dir). Effectively a fresh install.
curl -sX POST -H "x-api-key: $BACKEND_SHARED_SECRET" $OE_API/fixtures/reset

Red: /chat

POST /chat runs the orchestrator end-to-end. Calling it from Claude would impersonate the user, log spurious turns to the audit trail, and (if x-caller-email matches the user) pollute their Honcho peer card. Document, don't invoke. If the user explicitly asks for a chat test from curl, treat as red and confirm.

Output handling

• Always pipe JSON to jq so the transcript stays readable.
• For long responses, project early: jq '.sections | length', jq '.[] | {id, status}', jq '.audit_events[0:3]'. Don't dump full bodies into Claude's context.
• For text/streaming endpoints, redirect to a temp file and head/grep.

Endpoint discovery

If you need a route this skill doesn't list, the authoritative source is packages/core/openexecutive/api/routes/. One file per router. Grep for @router.get|@router.post|@router.delete|@router.patch to enumerate. Do not guess endpoints — the backend's middleware will 401 you on the wrong path with the api-key header.

Common gotchas

• localhost:8000 requires make dev running. If curl returns "Connection refused," the dev server is down.
• x-api-key middleware applies to nearly all routes. A bare GET /health works without it, but most others 401 without the header.
• The UI proxies through /api/backend/... and re-stamps x-caller-email from the verified session. Hitting the API directly bypasses that — useful for testing, but means you control the caller identity (and have to set it accurately).
• After POST /fixtures/reset, the Honcho workspace is wiped. The next chat turn rebuilds it lazily; don't expect prior conversation memory.