REST API

The Selu orchestrator exposes a REST API on port 8080 by default. All endpoints require authentication via a Bearer token unless noted otherwise.

Base URL

http://localhost:8080/api/v1

Set SELU_API_BASE_URL to override the base URL when the orchestrator runs behind a reverse proxy.

Authentication

Include your API token in the Authorization header:

Authorization: Bearer <your-api-token>

Generate a token with selu token create or from the dashboard under Settings → API Tokens.

Endpoints overview

Method	Path	Description
GET	/agents	List all installed agents.
GET	/agents/{name}	Get details for a specific agent.
POST	/agents	Install a new agent from a registry or local path.
DELETE	/agents/{name}	Uninstall an agent and remove its container.
POST	/agents/{name}/restart	Restart an agent’s runtime container.
GET	/capabilities	List all registered capabilities.
GET	/capabilities/{name}	Get capability details and manifest.
GET	/channels	List configured channels.
POST	/channels	Add a new channel configuration.
DELETE	/channels/{id}	Remove a channel.
POST	/conversations	Start a new conversation with an agent.
POST	/conversations/{id}/messages	Send a message in an existing conversation.
GET	/conversations/{id}	Retrieve conversation history.
GET	/health	Orchestrator health status (no auth required).

Example: list agents

Request

curl -s http://localhost:8080/api/v1/agents \
  -H "Authorization: Bearer $SELU_TOKEN"

Response

{
  "agents": [
    {
      "name": "research-assistant",
      "version": "1.2.0",
      "status": "running",
      "channels": ["web", "telegram"],
      "capabilities": ["web-search", "file-writer"]
    }
  ]
}

Example: send a message

Request

curl -s -X POST http://localhost:8080/api/v1/conversations/conv_abc123/messages \
  -H "Authorization: Bearer $SELU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Summarize the latest news on AI regulation."}'

Response

{
  "message_id": "msg_def456",
  "role": "assistant",
  "content": "Here is a summary of recent AI regulation developments...",
  "capabilities_used": ["web-search"],
  "timestamp": "2026-03-03T10:15:30Z"
}

Note

Full OpenAPI specs are auto-generated and available at /api/v1/openapi.json when the orchestrator is running. Import this file into tools like Swagger UI or Redocly for interactive exploration.

Error format

All errors follow a consistent structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent 'foo' is not installed.",
    "request_id": "req_789xyz"
  }
}

Standard HTTP status codes apply: 400 for validation errors, 401 for missing/invalid auth, 404 for unknown resources, and 500 for internal failures.