Skip to main content
The roz server exposes a REST API alongside the gRPC API. Both are multiplexed on the same port (default localhost:8080). REST is used for resource management; gRPC is used for real-time agent sessions. All REST endpoints require authentication via API key header: Authorization: Bearer roz_sk_... The only exceptions are /health and the device auth endpoints.

​
Authentication

​
API Keys

# Create a key (self-hosted)
curl -X POST http://localhost:8080/api/v1/auth-keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key"}'

# List keys
curl http://localhost:8080/api/v1/auth-keys \
  -H "Authorization: Bearer $ROZ_API_KEY"
API keys use the scheme roz_sk_<random>. Keys do not expire by default — they are permanent until explicitly revoked.

​
Device Auth

For CLI login without browser redirect: 
# Request device code
curl -X POST http://localhost:8080/api/v1/device/code

# Poll for token (user approves in browser)
curl -X POST http://localhost:8080/api/v1/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "..."}'

​
Tasks

Tasks represent agent work items — a prompt to execute with a specific configuration.
MethodPathDescription
POST/api/v1/tasksCreate a new task
GET/api/v1/tasksList tasks (with pagination)
GET/api/v1/tasks/:idGet task details
POST/api/v1/tasks/:id/transitionTransition task state

​
Environments

Environments define a robot configuration — which host, which safety policies, which tools are available.
MethodPathDescription
POST/api/v1/environmentsCreate environment
GET/api/v1/environmentsList environments
GET/api/v1/environments/:idGet environment
PUT/api/v1/environments/:idUpdate environment
DELETE/api/v1/environments/:idDelete environment

​
Hosts

Hosts are registered edge workers (robots or compute nodes).
MethodPathDescription
POST/api/v1/hostsRegister a host
GET/api/v1/hostsList hosts
GET/api/v1/hosts/:idGet host details
PUT/api/v1/hosts/:id/statusUpdate host status

​
Safety Policies

Define safety constraints that are enforced at runtime.
MethodPathDescription
POST/api/v1/safety-policiesCreate policy
GET/api/v1/safety-policiesList policies
GET/api/v1/safety-policies/:idGet policy
PUT/api/v1/safety-policies/:idUpdate policy
DELETE/api/v1/safety-policies/:idDelete policy

​
Commands

Robot commands with state machine transitions (pending → running → completed/failed).
MethodPathDescription
POST/api/v1/commandsCreate command
GET/api/v1/commandsList commands
GET/api/v1/commands/:idGet command
POST/api/v1/commands/:id/transitionTransition state
DELETE/api/v1/commands/:idDelete command

​
Triggers

Scheduled or event-driven task execution.
MethodPathDescription
POST/api/v1/triggersCreate trigger
GET/api/v1/triggersList triggers
DELETE/api/v1/triggers/:idDelete trigger

​
Health

curl http://localhost:8080/health
# Returns: {"status": "ok"}
No authentication required.

​
Metrics

curl http://localhost:8080/api/v1/metrics/tasks \
  -H "Authorization: Bearer $ROZ_API_KEY"
Returns aggregate task metrics (counts by status, average duration).

​
Source Code

  • Routes: crates/roz-server/src/routes/
  • All endpoints use tenant-scoped Row Level Security (RLS) — each API key is bound to a tenant, and queries only return that tenant’s data.