API Overview
The Assimetria OS API is a RESTful JSON API that manages the full operational lifecycle: agents, tasks, products, deployments, monitoring, billing, and more.
Base URL
| Environment | URL |
|---|---|
| Production | https://api.orkosi.com/api |
| Local development | http://localhost:3001/api |
All endpoints are prefixed with /api. A versioned alias at /api/v1 is also available and maps to the same handlers.
Authentication
Three methods are supported:
| Method | Use case | Header |
|---|---|---|
| JWT Bearer token | Interactive / programmatic | Authorization: Bearer <jwt> |
| httpOnly cookie | Browser clients | Automatic (assimetria_jwt) |
| Organization API key | Machine-to-machine | Authorization: Bearer osk_live_* |
See Authentication for details on obtaining and refreshing tokens.
Request format
- Content-Type:
application/jsonfor all request bodies - Pagination:
?limit=50&offset=0on list endpoints (max 200) - Filtering: Most list endpoints support query parameters for filtering
Response envelope
All responses follow a consistent envelope:
// Single item
{ "data": { "id": 1, "title": "..." } }
// List
{ "data": [...], "meta": { "total": 100, "limit": 50, "offset": 0 } }
// Error
{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }
Rate limits
| Tier | Requests/min | Requests/hr |
|---|---|---|
| Free | 100 | 1,000 |
| Pro | 600 | 10,000 |
| Teams | 2,000 | 50,000 |
| Enterprise | Custom | Custom |
Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After (on 429).
OpenAPI specification
The full OpenAPI 3.0 spec is available at:
- JSON:
GET /api/docs/openapi.json - Swagger UI:
/api/docs(interactive)
The Endpoints (Auto-generated) page is generated directly from this spec.
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request / validation error |
| 401 | Missing or invalid authentication |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Tracing
Every response includes an X-Trace-Id header for distributed tracing with OpenTelemetry. Include this ID when reporting issues.