API Reference

REST endpoints and SSE streaming.

Overview

otto exposes a local HTTP API via Hono. The server supports both REST endpoints and Server-Sent Events (SSE) for streaming.

Base URL: http://localhost:<port>

For first-party clients (web, desktop, tui), prefer the generated @ottocode/api SDK over direct fetch calls.

Ask (Streaming)

POST /api/ask

Send a prompt and stream the response via SSE.

POST /api/ask
Content-Type: application/json

{
  "prompt": "explain this error",
  "sessionId": "optional-session-id",
  "agent": "build",
  "provider": "anthropic",
  "model": "claude-sonnet-4"
}

Returns an SSE stream with events:

• text-delta — text chunk
• tool-call — tool invocation
• tool-result — tool execution result
• finish — stream complete
• error — error occurred

Sessions

GET /api/sessions

List all sessions.

GET /api/sessions?limit=20&offset=0

GET /api/sessions/:id

Get a specific session with messages.

DELETE /api/sessions/:id

Delete a session.

Messages

GET /api/sessions/:id/messages

Get messages for a session.

Configuration

GET /api/config

Get current configuration.

GET /api/models

List available models for a provider.

GET /api/agents

List available agents.

Git

GET /api/git/status

Get git status for the current working directory.

GET /api/git/diff

Get git diff.

Files

GET /api/files

List files in a directory.

GET /api/files/:path

Read file contents.

Auth

GET /api/auth/providers

List configured providers and their auth status.

Health

GET /health

Health check endpoint. Returns 200 OK.

OpenAPI

Full OpenAPI spec available at /openapi.json.

Updating the API contract

1. Add/update route methods in packages/server/src/routes/
2. Update packages/server/src/openapi/spec.ts
3. Regenerate OpenAPI JSON and SDK with bun run --filter @ottocode/api generate
4. Consume the new methods from @ottocode/api in client apps

TypeScript Client

Use the generated type-safe client:

import { createClient } from "@ottocode/api";

const client = createClient({
  baseUrl: "http://localhost:9100",
});

const sessions = await client.getSessions();
const models = await client.getModels({ provider: "anthropic" });