API Reference

All endpoints are served from http://{host}:{port}/api/.

Authentication

All /api/* endpoints (except /api/auth/*) require a JWT token, passed via the Authorization: Bearer <token> header or the token query parameter.

Login

POST /api/auth/login

{
  "username": "admin",
  "password": "secret"
}

Response: 200 OK

{
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG...",
  "expires_in": 3600
}

Refresh Token

POST /api/auth/refresh

{
  "refresh_token": "eyJhbG..."
}

Response: 200 OK

{
  "access_token": "eyJhbG...",
  "expires_in": 3600
}

Workers

Create Worker

POST /api/workers

{
  "name": "Assistant",
  "description": "General purpose assistant",
  "memory": "You are a helpful assistant.",
  "work_dir": "/path/to/project"
}

Only name is required. All other fields are optional.

Response: 201 Created

{
  "id": "uuid",
  "name": "Assistant",
  "description": "General purpose assistant",
  "memory": "You are a helpful assistant.",
  "work_dir": "/home/user/.openbee/worker/uuid",
  "status": "idle",
  "created_at": 1711180800000,
  "updated_at": 1711180800000
}

List Workers

GET /api/workers

Response: 200 OK — Array of worker objects.

Get Worker

GET /api/workers/:id

Response: 200 OK — Single worker object.

Update Worker

PUT /api/workers/:id

{
  "name": "Updated Name",
  "description": "Updated description",
  "memory": "Updated memory"
}

All fields are optional (patch semantics).

Response: 200 OK — Updated worker object.

Delete Worker

DELETE /api/workers/:id?delete_work_dir=true

The delete_work_dir query parameter is optional. When set to true, the worker's work directory is also removed.

Response: 200 OK

{
  "status": "deleted"
}

Executions

List All Executions

GET /api/executions

Response: 200 OK — Array of execution objects.

Get Execution

GET /api/executions/:id

Response: 200 OK — Single execution object.

Get Execution Logs

GET /api/executions/:id/logs

Response: 200 OK — Plain text log content. Completed execution logs include a Cache-Control: public, max-age=3600 header.

List Worker Executions

GET /api/workers/:id/executions

Response: 200 OK — Array of execution objects for the specified worker.

List Session Executions

GET /api/sessions/:sessionId/executions

Response: 200 OK — Array of execution objects for the specified session.

Local Chat

Create Session

POST /api/local/sessions

{
  "name": "My Chat"
}

Response: 201 Created

{
  "id": "session-uuid",
  "name": "My Chat",
  "created_at": 1711180800000,
  "updated_at": 1711180800000
}

List Sessions

GET /api/local/sessions

Response: 200 OK — Array of local session objects.

Delete Session

DELETE /api/local/sessions/:id

Cascading delete: removes all messages, replies, and session contexts associated with the session.

Response: 200 OK

{
  "status": "deleted"
}

Send Message

POST /api/local/sessions/:id/messages

{
  "content": "Hello, what can you do?",
  "media_path": "/optional/path/to/uploaded/file"
}

Only content is required. media_path is optional and must point to a file within the session's upload directory.

Response: 202 Accepted

{
  "status": "queued"
}

Get Messages

GET /api/local/sessions/:id/messages

Response: 200 OK — Array of chat messages (both user and bee messages), sorted by timestamp.

[
  {
    "role": "user",
    "content": "Hello",
    "ts": 1711180800000
  },
  {
    "role": "bee",
    "content": "Hi there!",
    "ts": 1711180801000
  }
]

Upload Media

POST /api/local/sessions/:id/media

Multipart form data with a file field.

Response: 200 OK

{
  "path": "/home/user/.openbee/local-uploads/session-uuid/filename.png"
}

Stream Replies

GET /api/local/sessions/:id/stream

Response: Server-Sent Events (SSE) stream of worker replies.