API Reference

# REST base URL (local default)
http://localhost:8080/api/v1
# WebSocket (outside /api/v1)
ws://localhost:8080/ws

# Health check: no token needed
curl http://localhost:8080/healthz
# {"status":"ok","runtime":"up","runtime_mode":"simulation"}

# Sign in: access token in the body, refresh token in an HttpOnly cookie
curl -i -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"<password>"}'
# 200 {"token_type":"Bearer","access_token":"<token>","expires_in":900,
#      "expires_at":"...","user":{...},"org_id":"<org id>","role":"owner"}

# Call the API with the access token
curl http://localhost:8080/api/v1/agents -H 'Authorization: Bearer <token>'

# Renew the session: cookie + CSRF header
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -b 'wfai_refresh=<cookie value>' -H 'X-WFAI-CSRF: 1'

# Create a token (admin session); the plaintext is returned once
curl -X POST http://localhost:8080/api/v1/governance/tokens \
  -H 'Authorization: Bearer <session token>' -H 'Content-Type: application/json' \
  -d '{"name":"crm-sync","scopes":["requests:write","reports:read"],"expires_in_days":90}'
# 201 {"token":"<api token>","item":{...},"note":"shown once"}

# Use it against the public API
curl -X POST http://localhost:8080/api/public/v1/requests \
  -H 'Authorization: Bearer <api token>' -H 'Content-Type: application/json' \
  -d '{"text":"Summarize the open deals of this week"}'
# 202 {"request_id":"<id>"}

// Most routes
{ "error": "invalid input: text is required" }

// Some domains (connections, controls, drive, shop...) add a stable code
{ "error": "conflict: not enough coins", "code": "insufficient_coins" }

// /auth/* routes and permission failures
{ "error": { "code": "forbidden", "message": "insufficient permissions" } }

// Auth validation (422) lists the fields that failed
{ "error": { "code": "validation_failed", "message": "invalid input",
             "fields": { "password": "..." } } }

# Submit a request: asynchronous, progress arrives over the WebSocket
curl -X POST http://localhost:8080/api/v1/requests \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"text":"Prepare a $50,000 proposal for ACME","budget_cap_usd":5}'
# 202 {"request_id":"<id>"}

# Chat with the office (a retry with the same key returns the first turn)
curl -X POST http://localhost:8080/api/v1/messages \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7d1e...' \
  -d '{"conversation":"office","text":"Who is free today?"}'
# 202 turn object; replies arrive as chat.message events

{
  "id": "<request id>",
  "text": "Prepare a $50,000 proposal for ACME",
  "status": "running",
  "created_at": "2026-01-01T12:00:00Z",
  "report_id": null,
  "cost_usd": 0.0123,
  "tasks": [
    {
      "id": "<task id>",
      "request_id": "<request id>",
      "workflow_id": null,
      "title": "Draft the commercial proposal",
      "description": "...",
      "agent_id": "sales",
      "status": "running",
      "depends_on": [],
      "parent_task_id": null,
      "created_at": "2026-01-01T12:00:02Z",
      "started_at": "2026-01-01T12:00:03Z",
      "finished_at": null,
      "output": null
    }
  ],
  "plan": {
    "objectives": ["..."],
    "clarifying_questions": [],
    "tasks": [
      { "id": "<task id>", "title": "Draft the commercial proposal",
        "agent_id": "sales", "depends_on": [] }
    ]
  },
  "budget_cap_usd": 5
}

# List pending approvals
curl 'http://localhost:8080/api/v1/approvals?status=pending' \
  -H 'Authorization: Bearer <token>'

# Approve (admin or owner)
curl -X POST http://localhost:8080/api/v1/approvals/<id>/decision \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"decision":"approve","note":"ok"}'
# 200 the updated approval; "decision" is "approve" or "reject"

# Create a draft project
curl -X POST http://localhost:8080/api/v1/projects/draft \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"goal":"Launch the spring campaign","budget_usd":200}'
# 201 {"project_id":"<id>"}

# Launch it with an approved budget (required, greater than 0)
curl -X POST http://localhost:8080/api/v1/projects/<id>/launch \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"approved_budget_usd":200}'
# 202 {"ok":true,"project":{...}}

curl http://localhost:8080/api/v1/rewards/wallet -H 'Authorization: Bearer <token>'

curl -X POST http://localhost:8080/api/v1/shop/purchases \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <unique key>' \
  -d '{"item_id":"<item id>"}'
# 201 first purchase; 200 when the same key is replayed

# Upload a file to the drive (raw body)
curl -X PUT 'http://localhost:8080/api/v1/drive/upload?path=/Shared/plan.xlsx' \
  -H 'Authorization: Bearer <token>' --data-binary @plan.xlsx
# 201 created, 200 new version

# Pause one agent (action: pause | resume | read_only | read_write)
curl -X POST http://localhost:8080/api/v1/agents/<id>/control \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"action":"pause","drain":"graceful","reason":"maintenance"}'

# Organization kill switch (level: freeze | lockdown)
curl -X POST http://localhost:8080/api/v1/org/controls/kill-switch \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"level":"freeze","reason":"incident"}'

curl -X POST http://localhost:8080/api/v1/connections \n  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \n  -d '{"provider":"custom_api","kind":"api_key","label":"ERP","secret":"<api-key>",
       "source":{"base_url":"https://erp.example.com/api",
                 "auth":{"style":"header","name":"X-API-Key"},
                 "description":"Inventory, orders and customers",
                 "endpoints":[{"name":"stock","path":"/products/{sku}/stock","params":["warehouse"]}]}}'

# What an agent asks for (the backend runs it; the agent never sees the key):
# {"tool":"api","action":"get","args":{"connection_alias":"erp","endpoint":"stock","params":{"sku":"A-1"}}}

# Browsers cannot set headers on a WebSocket: pass the token in the query string
wscat -c 'ws://localhost:8080/ws?access_token=<token>'

< {"id":"...","type":"hello","ts":"...","org_id":"<org id>","payload":{"agents":[...]}}
< {"id":"...","type":"agent.state_changed","ts":"...","org_id":"<org id>","agent_id":"sales","payload":{...}}

# Frame shape
{ "id": "<uuid>", "type": "<event.type>", "ts": "<RFC 3339>",
  "org_id": "<org id>", "agent_id": "<optional>", "payload": { } }