openexec-api

name

openexec-api

description

Interact with the Open Executive FastAPI backend via curl. Use this skill when the user asks to hit /chat, /today, /people, /scheduled_actions, /architecture/*, /health/*, /fixtures/*, /audit/*, or any HTTP endpoint on openexec-api-dev.fly.dev (dev) or localhost:8000 (local). Authenticates via $BACKEND_SHARED_SECRET in the x-api-key header. Tiered safety: GET runs freely, mutating POSTs need explicit confirmation.

openexec-api

Curl recipes against the FastAPI backend. Pair skill: flyctl (infra ops). When the user wants an SQLite row or to tail logs, that's flyctl. When they want to hit an HTTP route, that's this skill.

Base URLs

export OE_API=https://openexec-api-dev.fly.dev   # dev (default in this skill)
export OE_API=http://localhost:8000               # local (`make dev` must be running)

All recipes below use $OE_API. If the user doesn't specify, assume dev.

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.

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.