HTTP API Reference

All routes are mounted under the configured eveMount (default: /eve/v1).

GET /eve/v1/health

Health check. Returns server status.

Response 200 OK

{
  "ok": true,
  "status": "ready",
  "workflowId": "wf_compat"
}

GET /eve/v1/info

Server and agent metadata.

Response 200 OK

{
  "agent": {
    "name": "assistant",
    "model": "anthropic/claude-sonnet-4-6"
  },
  "tools": [
    {
      "name": "lookup_order",
      "description": "Look up an order by ID",
      "parameters": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string" }
        },
        "required": ["orderId"]
      }
    }
  ],
  "connections": []
}

When connections are configured, tools includes connection__* entries:

{
  "tools": [
    {
      "name": "connection__linear_search",
      "description": "Search Linear issues",
      "parameters": { /* ... */ }
    }
  ]
}

POST /eve/v1/session

Create a new session.

Request body

{
  "message": "Hello, world!",
  "agent": "assistant",
  "outputSchema": {
    "type": "object",
    "properties": {
      "answer": { "type": "string" }
    }
  },
  "clientContext": {
    "userId": "user-123",
    "tier": "pro"
  }
}

Field	Type	Required	Description
`message`	`string`	Yes	The user's message
`agent`	`string`	No	Agent name (uses default if omitted)
`outputSchema`	`object`	No	JSON Schema for structured output
`clientContext`	`object`	No	Arbitrary context for the agent

Response 202 Accepted

{
  "sessionId": "ses_abc123",
  "continuationToken": "tok_xyz789"
}

Headers:

x-eve-session-id: ses_abc123

The session starts streaming immediately. Connect to GET /session/:id/stream to receive events.

POST /eve/v1/session/:sessionId

Send a follow-up message to an existing session (multi-turn conversation).

Headers

Authorization: Bearer <continuationToken>

Request body

{
  "message": "Tell me more",
  "agent": "assistant",
  "continuationToken": "tok_xyz789",
  "outputSchema": { /* ... */ },
  "inputResponses": { "approved": true }
}

Field	Type	Required	Description
`message`	`string`	No	The user's message (omitted for HITL resume)
`agent`	`string`	No	Agent name (optional per-turn routing)
`continuationToken`	`string`	Yes	Token from the session response
`outputSchema`	`object`	No	JSON Schema for structured output
`inputResponses`	`object`	No	HITL input responses (resume from park)

Response 200 OK

{
  "sessionId": "ses_abc123",
  "continuationToken": "tok_xyz789"
}

Error responses

Code	Meaning
409	Stale `continuationToken` — turn is still active
410	Terminal session — cannot accept more messages
404	Session not found

GET /eve/v1/session/:sessionId/stream

Stream events for a session. Returns NDJSON (application/x-ndjson; charset=utf-8).

Query parameters

Parameter	Type	Description
`startIndex`	`number`	Replay from this journal index (optional)

Response headers

content-type: application/x-ndjson; charset=utf-8
x-eve-stream-format: ndjson
x-eve-stream-version: 16
cache-control: no-cache
connection: keep-alive

Response body (NDJSON, one JSON event per line)

{"type":"session.started","data":{}}
{"type":"agent.start","streamIndex":0}
{"type":"agent.content.delta","data":{"text":"Hello"},"streamIndex":1}
{"type":"agent.content.delta","data":{"text":"!"},"streamIndex":2}
{"type":"message.appended","data":{"id":"msg_1","role":"assistant","content":"Hello!"},"streamIndex":3}
{"type":"agent.complete","streamIndex":4}
{"type":"session.waiting","streamIndex":5}

Error responses

Code	Meaning
400	Invalid `startIndex` (negative or NaN)
404	Session not found

Error response format

All errors follow the same shape:

{
  "error": {
    "code": "session_not_found",
    "message": "Session ses_abc123 not found"
  }
}

See error reference for the complete error catalog.