O

ORCHESTRATOR

API DOCUMENTATION

PLAYGROUNDGET API KEY

API DOCUMENTATION

The Orchestrator Agent Brain API provides RESTful endpoints and Server-Sent Events for real-time AI agent orchestration with sandboxed tool execution.

Base URL
http://localhost:3001/v1

Replace with your production URL in live environments

REST + SSE

RESTful API with Server-Sent Events for real-time streaming

Multi-LLM

Support for GPT-4, Claude, and custom models via profiles

Sandboxed

Isolated Docker execution with configurable profiles

SERVICE URLS

The Orchestrator system consists of multiple microservices. Here are the connection details for each service in different environments.

Backend API

Core Agent Brain REST API + SSE streams

REQUIRED
Local Dev:http://localhost:3001
Production:https://api.orchestrator.ai
All API endpoints described in this documentation use this base URL with /v1 prefix

Admin Panel

Web UI for managing agents, sessions, and configurations

OPTIONAL
Local Dev:http://localhost:3002
Production:https://admin.orchestrator.ai
Features: Playground, Agent Templates, Models, Sessions, Profiles, Policies, Real-time Terminal & Debug views

Frontend Application

Public-facing website and documentation (you are here)

PUBLIC
Local Dev:http://localhost:3000
Production:https://orchestrator.ai
Features: Marketing pages, Documentation (this page), Public Playground, Sign up
Quick Start Guide
  1. 1.
    Get your Tenant ID: Contact your administrator or sign up for access
  2. 2.
    Test with Admin Panel: Open http://localhost:3002 → Playground → Configure & test your agent
  3. 3.
    Integrate with API: Use http://localhost:3001/v1 endpoints from your application
  4. 4.
    Monitor Sessions: View sessions, debug events, and terminal output in Admin Panel
CORS & Network Configuration

For local development, ensure your application can reach the Backend API:

  • Backend API must be running on http://localhost:3001
  • CORS is configured to allow requests from localhost:3000 and localhost:3002
  • For production, configure environment variables with your production URLs
  • SSE streams require persistent connections (no proxies that buffer responses)

AUTHENTICATION

Orchestrator uses tenant-based authentication. Include your tenant ID in the X-NS-Tenant header (or tenant query parameter) with every request.

bash
curl http://localhost:3001/v1/sessions \
  -H "X-NS-Tenant: your-tenant-id" \
  -H "Content-Type: application/json"
Tenant ID Required

All requests must include a valid tenant ID. Contact your administrator to get your tenant ID.

SESSIONS

Create Session

POST /v1/sessions

Create a new agent session. Sessions can be task-based (using a pre-defined task) or direct (with custom configuration).

Request Headers

  • X-NS-Tenant - Your tenant ID (required)
  • Idempotency-Key - Unique key for idempotent creation (required)
  • Content-Type - application/json
bash
# Task-based session
curl -X POST http://localhost:3001/v1/sessions \
  -H "X-NS-Tenant: tenant_123" \
  -H "Idempotency-Key: ${uuidv4()}" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "task_code_review",
    "taskArgs": {
      "repository": "myorg/myrepo",
      "branch": "main"
    }
  }'

# Direct session with custom prompt
curl -X POST http://localhost:3001/v1/sessions \
  -H "X-NS-Tenant: tenant_123" \
  -H "Idempotency-Key: ${uuidv4()}" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are an expert code reviewer...",
    "promptId": "prompt_default",
    "profileId": "profile_gpt4",
    "allowedTools": ["code_executor", "file_system"]
  }'

Request Body Options

taskId (string, optional)

ID of pre-configured task to use

taskBlueprint (object, optional)

Inline task blueprint: { id, args, version }

systemPrompt (string, optional)

Custom system prompt (max 4096 chars)

promptId (string, optional)

Pre-configured prompt ID

profileId (string, optional)

Sandbox profile ID (model, resources, etc.)

allowedTools (string[], optional)

List of tool IDs available to agent

initialMessages (array, optional)

Pre-populate conversation history

policyOverrides (object, optional)

Override default policies

Response

json
{
  "sessionId": "sess_01JCXYZ...",
  "status": "active",
  "plan": [
    {
      "id": "step_1",
      "title": "Initialize repository scan",
      "status": "pending",
      "dependencies": []
    }
  ]
}

Get Session

GET /v1/sessions/:sessionId
bash
curl http://localhost:3001/v1/sessions/sess_01JCXYZ \
  -H "X-NS-Tenant: tenant_123"

List Sessions

GET /v1/sessions
bash
curl http://localhost:3001/v1/sessions \
  -H "X-NS-Tenant: tenant_123"
  
# Response:
# {
#   "items": [
#     { "id": "sess_...", "status": "active", ... },
#     { "id": "sess_...", "status": "completed", ... }
#   ]
# }

MESSAGES

Send Message

POST /v1/sessions/:sessionId/messages

Send a user message to the agent and trigger a turn execution. The agent will process the message using LLM and execute any needed tools.

bash
curl -X POST http://localhost:3001/v1/sessions/sess_01JCXYZ/messages \
  -H "X-NS-Tenant: tenant_123" \
  -H "Idempotency-Key: ${uuidv4()}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Review the authentication middleware in src/auth.ts"
  }'
💡 Idempotency

Use the Idempotency-Key header to safely retry message sends. Same key returns cached response.

SSE STREAMING

Stream real-time session events using Server-Sent Events (SSE). Get LLM tokens, tool execution updates, and approval requests as they happen.

Connect to Stream

GET /v1/sessions/:sessionId/stream
bash
# Stream from beginning
curl -N http://localhost:3001/v1/sessions/sess_01JCXYZ/stream \
  -H "X-NS-Tenant: tenant_123"

# Resume from event cursor
curl -N "http://localhost:3001/v1/sessions/sess_01JCXYZ/stream?cursor=42" \
  -H "X-NS-Tenant: tenant_123"
  
# Or use Last-Event-ID header
curl -N http://localhost:3001/v1/sessions/sess_01JCXYZ/stream \
  -H "X-NS-Tenant: tenant_123" \
  -H "Last-Event-ID: 42"

Event Types

session.created - Session initialized
message.received - User message received
turn.started - LLM turn execution started
assistant.delta - Streaming LLM token
assistant.message - Complete assistant message
tool.start - Tool execution started
tool.update - Tool progress update
tool.finish - Tool execution complete
approval.required - Human approval needed
approval.resolved - Approval decision made
turn.completed - Turn execution finished
plan.snapshot - Plan state updated
error - Error occurred

APPROVALS

When a tool requires approval, the session pauses and emits an approval.required event. You must approve or deny before the agent continues.

Make Approval Decision

POST /v1/sessions/:sessionId/approvals/:approvalId/decision
bash
# Approve
curl -X POST http://localhost:3001/v1/sessions/sess_01JCXYZ/approvals/appr_123/decision \
  -H "X-NS-Tenant: tenant_123" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "reason": "Verified args are safe"
  }'

# Deny
curl -X POST http://localhost:3001/v1/sessions/sess_01JCXYZ/approvals/appr_123/decision \
  -H "X-NS-Tenant: tenant_123" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "denied",
    "reason": "Unsafe operation"
  }'

Decision Options

decision (string, required)

Either "approved" or "denied"

reason (string, optional, max 1024 chars)

Explanation for the decision

List Pending Approvals

GET /v1/sessions/:sessionId/approvals
bash
curl http://localhost:3001/v1/sessions/sess_01JCXYZ/approvals \
  -H "X-NS-Tenant: tenant_123"
  
# Response:
# {
#   "items": [
#     {
#       "id": "appr_123",
#       "prompt": "Execute shell command: npm install",
#       "status": "pending",
#       "createdAt": "2024-01-15T10:30:00Z"
#     }
#   ]
# }

TOOLS

List Available Tools

GET /v1/tools
bash
# List all tools
curl http://localhost:3001/v1/tools \
  -H "X-NS-Tenant: tenant_123"

# List tools allowed for a specific session
curl "http://localhost:3001/v1/tools?allowedForSession=sess_01JCXYZ" \
  -H "X-NS-Tenant: tenant_123"

TASKS

Tasks are pre-configured agent blueprints with prompts, tools, and execution plans.

Get Task

GET /v1/tasks/:taskId
bash
curl http://localhost:3001/v1/tasks/task_code_review \
  -H "X-NS-Tenant: tenant_123"

ERROR HANDLING

The API returns standard HTTP status codes and error responses in JSON format.

Error Response Format

json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": [
      {
        "field": "taskId",
        "issue": "Required field missing"
      }
    ]
  }
}

HTTP Status Codes

200 OK - Request successful
201 Created - Resource created
400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid tenant ID
404 Not Found - Resource not found
409 Conflict - Idempotency key conflict
500 Server Error - Internal server error

Common Error Codes

auth.missing_tenant

Missing X-NS-Tenant header

not_found.session

Session ID not found for tenant

not_found.approval

Approval ID not found

validation_error

Request validation failed

READY TO START?

Get your tenant ID and start building with Orchestrator today.

GET STARTEDTRY PLAYGROUND