Skip to content

api.md

Latest commit

 

History

History
104 lines (70 loc) · 2.34 KB

api.md

File metadata and controls

104 lines (70 loc) · 2.34 KB

API Reference

FastAPI server providing HTTP endpoints for chat, status, and events.

Starting the Server

hexis api [--host HOST] [--port PORT]

Default: 127.0.0.1:43817

Authentication

Optional Bearer token via HEXIS_API_KEY environment variable. If unset, no auth is required.

curl -H "Authorization: Bearer <token>" http://localhost:43817/api/status

Endpoints

GET /health

Health check.

Response: {"status": "ok", "checks": {"db": true}}

GET /api/status

Rich agent status.

Response: Full status payload including identity, memory counts, energy level, heartbeat info.

POST /api/chat

Streaming chat via SSE. The primary conversation endpoint.

Request body:

{
  "message": "Hello, how are you?",
  "history": [],
  "prompt_addenda": ""
}

SSE events:

Event Data Description
phase_start {"phase": "string"} Processing phase started
phase_end {"phase": "string"} Processing phase completed
token {"phase": "string", "text": "string"} Streaming text delta
log {"id", "kind", "title", "detail"} Tool call/result/memory log
done {"assistant": "full_text"} Completion signal
error {"message": "string"} Error occurred

Log kinds: tool_call, tool_result, memory_recall, memory_write

POST /api/webhook/{source}

Accept external webhook events (e.g., from channels or external services).

Response: {"status": "accepted", "event_id": "..."}

GET /api/events/stream

SSE stream of gateway events. Listens on PostgreSQL pg_notify for real-time updates.

POST /api/init/consent/request

Trigger the consent flow for a model.

Request body:

{
  "role": "conscious",
  "llm": {
    "provider": "openai-codex",
    "model": "gpt-5.2"
  }
}

Response: Consent decision, contract, and recorded certificate.

CORS

Configurable via HEXIS_CORS_ORIGINS env var. Default: localhost:3477, localhost:3000.

Related