API Reference

Interactive REST API documentation auto-generated from the Agor daemon.

📚 Interactive API Docs

The Agor daemon serves live, interactive API documentation via Swagger UI:

agor daemon start

Features:

• ✅ Always up-to-date - Generated from actual service definitions
• ✅ Try it out - Execute API calls directly from the browser
• ✅ Dark mode - Easy on the eyes
• ✅ Full schema - Request/response models for all endpoints

Quick Reference

Base URL

http://localhost:3030

Authentication

Agor uses JWT-based authentication:

Authorization: Bearer <your-token>

Getting a Bearer Token

Use the CLI to authenticate and retrieve a token:

agor login

You’ll be prompted for your email and password. Your token is automatically saved to ~/.agor/cli-token and is valid for 7 days.

Using the token with cURL:

# 1. Get your token (already saved locally)
cat ~/.agor/cli-token
 
# 2. Use it in curl commands
curl -X GET http://localhost:3030/sessions \
  -H "Authorization: Bearer <your-token>"

Using the token in Swagger UI:

1. Visit http://localhost:3030/docs/
2. Click the “Authorize” button (🔒 icon in top-right)
3. Paste your Bearer token in the input field
4. Click “Authorize”
5. Now all generated curl commands and “Try it out” buttons will automatically include your token

Anonymous Mode: For local development, anonymous authentication is enabled by default (no token required).

Core Services

• /sessions - AI agent session management with genealogy (fork/spawn)
• /tasks - Work units within sessions tracking prompts and execution
• /messages - Conversation messages with streaming support
• /repos - Git repository management and worktree operations
• /boards - Spatial organization of sessions with zones and triggers
• /worktrees - Git worktree isolation for sessions
• /users - User account management and authentication
• /mcp-servers - Model Context Protocol server configurations

Response Format

All FeathersJS endpoints return data in this format:

// Single resource
{
  data: { id: '...', ... }
}
 
// List of resources (paginated)
{
  data: [{ id: '...', ... }],
  total: 100,
  limit: 50,
  skip: 0
}

RESTful Conventions

All services follow standard REST patterns:

• GET /service - List items (paginated)
• GET /service/:id - Get single item
• POST /service - Create new item
• PATCH /service/:id - Update item (partial)
• DELETE /service/:id - Delete item

Session Prompt Endpoint

Use POST /sessions/:id/prompt to send a prompt to an existing session.

curl -X POST http://localhost:3030/sessions/<session-id>/prompt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "prompt": "Review the latest auth changes for security issues",
    "permissionMode": "auto",
    "stream": true
  }'

Possible response shapes:

{
  "success": true,
  "taskId": "0195d3c0-82df-7a75-b9b3-83f58de12345",
  "status": "running",
  "streaming": true
}

{
  "success": true,
  "queued": true,
  "message": {
    "message_id": "0195d3c0-82df-7a75-b9b3-83f58de67890",
    "status": "queued"
  },
  "queue_position": 2
}

Message Content Shape

Message content supports both plain text and structured blocks:

• string
• ContentBlock[]

String content example:

{
  "role": "assistant",
  "content": "Implemented the fix and added tests."
}

Structured content example:

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Implemented the fix." },
    { "type": "thinking", "thinking": "Checking edge cases before final response." }
  ]
}

Browser Client Quick Start

import { createClient } from '@agor/core/api';
 
const client = createClient('http://localhost:3030', true);
 
await client.authenticate({
  strategy: 'jwt',
  accessToken: '<your-token>',
});
 
const sessions = await client.service('sessions').findAll({
  query: { $limit: 20 },
});
 
const promptResult = await client.sessions.prompt(
  sessions[0].session_id,
  'Summarize current progress and next steps',
  { stream: true }
);
 
console.log(promptResult);

WebSocket Events

Real-time updates via Socket.IO:

• WebSocket Events - Real-time event documentation

Source Code

For TypeScript type definitions and service implementations:

• TypeScript types: packages/core/src/types
• Service implementations: apps/agor-daemon/src/services