Apiary API Reference

Apiary provides both REST and gRPC APIs for managing resources. All APIs follow a consistent structure and use the same authentication and authorization mechanisms.

Base URL

REST API: http://localhost:8080/api/v1
gRPC API: localhost:8080 (default port)

Authentication

Currently, Apiary uses header-based authentication (MVP implementation). Set the following headers:

X-User-ID: <user-id>
X-User-Name: <user-name>

Note: This is an MVP implementation. Production should use JWT tokens or OAuth2/OIDC.

REST API

Cells

Cells provide namespace isolation. They are not namespaced themselves.

GET /api/v1/cells

List all cells

GET /api/v1/cells/:name

Get a specific cell

POST /api/v1/cells

Create a new cell

{
  "apiVersion": "apiary.io/v1",
  "kind": "Cell",
  "metadata": {
    "name": "my-cell"
  },
  "spec": {
    "resourceQuota": {
      "maxAgentSpecs": 100,
      "maxHives": 50
    }
  }
}

AgentSpecs

AgentSpecs define how to run an agent. They are namespaced to a Cell.

GET /api/v1/cells/:namespace/agentspecs

List all AgentSpecs in a cell

GET /api/v1/cells/:namespace/agentspecs/:name

Get a specific AgentSpec

POST /api/v1/cells/:namespace/agentspecs

Create a new AgentSpec

{
  "apiVersion": "apiary.io/v1",
  "kind": "AgentSpec",
  "metadata": {
    "name": "my-agent",
    "namespace": "default"
  },
  "spec": {
    "runtime": {
      "command": ["python", "agent.py"]
    },
    "interface": {
      "type": "stdin"
    },
    "resources": {
      "requests": {
        "cpu": 1000,
        "memory": 512000000
      }
    }
  }
}

POST /api/v1/cells/:namespace/agentspecs/:name/scale

Scale an AgentSpec

Hives

Hives are collections of agents that work together.

GET /api/v1/cells/:namespace/hives

List all hives

POST /api/v1/cells/:namespace/hives

Create a new hive

Sessions

Sessions manage stateful contexts for agent interactions.

GET /api/v1/cells/:namespace/sessions

List all sessions

POST /api/v1/cells/:namespace/sessions

Create a new session

Drones

Drones are running instances of agents.

GET /api/v1/cells/:namespace/drones

List all drones

gRPC API

The gRPC API mirrors all REST endpoints with the same functionality. Key RPCs include:

ListCells, GetCell, CreateCell, UpdateCell, DeleteCell
ListAgentSpecs, GetAgentSpec, CreateAgentSpec, UpdateAgentSpec, DeleteAgentSpec
ListHives, GetHive, CreateHive, UpdateHive, DeleteHive
ListSessions, GetSession, CreateSession, UpdateSession, DeleteSession
ListDrones, GetDrone, GetDroneLogs (streaming), ExecDrone (bidirectional streaming)

Error Codes

Common error codes:

NOT_FOUND: Resource does not exist
ALREADY_EXISTS: Resource already exists
INVALID_INPUT: Invalid request data
UNAUTHORIZED: Authentication required
FORBIDDEN: Insufficient permissions
INTERNAL_ERROR: Internal server error

Rate Limiting

Rate limiting is enforced per Cell and per user. Default limits:

100 requests/minute per user
1000 requests/minute per Cell

Pagination

List endpoints support pagination:

GET /api/v1/cells/:namespace/hives?limit=100&offset=0

Query Parameters:

limit: Maximum number of items to return (default: 100)
offset: Number of items to skip (default: 0)

Back to Documentation