API Reference

The Octavus API is a RESTful API that enables programmatic access to agent management and session execution.

Base URL

https://octavus.ai

Authentication

All API requests require authentication using a Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://octavus.ai/api/agents

API keys can be created in the Octavus Platform under your project's API Keys page.

For workloads that run in ephemeral or user-reachable environments (CI runners, serverless functions, per-user sandboxes), prefer a short-lived, scoped credential over a long-lived key - either an Octavus-minted ephemeral token or a federated workload-identity token you sign yourself. See Authentication.

Wire-Format Versioning

The Server SDK advertises the wire shape it understands via the X-Octavus-Sdk-Version header (set automatically). The platform currently serves the same shape to every request, so direct API users don't need to send it - the header exists so a future wire-incompatible change can be negotiated per client.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Octavus-Sdk-Version: 4" \
  https://octavus.ai/api/agent-sessions/SESSION_ID

The header value is the wire-format major the client can parse, not the SDK release version. A future wire-incompatible change bumps it again, and the platform will downgrade the shape for clients still on 4.

API Key Permissions

API keys have these permission scopes:

Both the Sessions and Agents permissions allow reading agent definitions (needed by CLI for sync and Server SDK for sessions).

Recommended setup: Use separate API keys for different purposes:

• CLI key with only "Agents" permission for CI/CD and development
• Server key with only "Sessions" permission for production applications

This limits the blast radius if a key is compromised.

Response Format

All responses are JSON. Success responses return the data directly (not wrapped in a data field).

Success Response

{
  "sessionId": "sess_abc123"
}

Error Response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found"
  }
}

HTTP Status Codes

Endpoints Overview

Agents

Sessions

Tokens

See Authentication for scoping, lifetimes, and federation.

Streaming

The trigger endpoint returns Server-Sent Events (SSE):

curl -N -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}' \
  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger

Response format:

data: {"type":"start","messageId":"..."}

data: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}

data: {"type":"text-start","id":"..."}

data: {"type":"text-delta","id":"...","delta":"Hello"}

data: {"type":"text-delta","id":"...","delta":"!"}

data: {"type":"text-end","id":"..."}

data: {"type":"block-end","blockId":"..."}

data: {"type":"finish","finishReason":"stop"}

data: [DONE]

SDKs

We recommend using our SDKs instead of calling the API directly:

• Server SDK: @octavus/server-sdk - For Node.js backends
• React SDK: @octavus/react - For React applications
• Client SDK: @octavus/client-sdk - For other frontend frameworks

The SDKs handle authentication, streaming, and tool execution automatically.