Octavus Docs

API Reference

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

Base URL

text

Authentication

All API requests require authentication using a Bearer token:

bash

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

Response Format

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

Success Response

json

Error Response

json

HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid API key
403Forbidden - Insufficient permissions
404Not Found
500Internal Server Error

Endpoints Overview

Agents

MethodEndpointDescription
GET/api/agentsList all agents
GET/api/agents/:idGet agent by ID
POST/api/agentsCreate agent
PATCH/api/agents/:idUpdate agent

Sessions

MethodEndpointDescription
POST/api/agent-sessionsCreate session
GET/api/agent-sessions/:idGet session state
POST/api/agent-sessions/:id/triggerExecute trigger (SSE)

Streaming

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

bash

Response format:

text

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.