REST API Overview

Raworc provides a comprehensive REST API for accelerating agent development from prototype to production. The API enables programmatic control over containerized sessions, computer-use capabilities, multi-agent orchestration, and enterprise operations.

Base Information

• Base URL: http://your-server:9000/api/v0
• Protocol: HTTP/HTTPS
• Format: JSON
• Authentication: Bearer token (JWT)

Authentication

All API endpoints (except /health, /version, and /auth/login) require authentication using a JWT bearer token.

Workspaces

Raworc uses spaces to organize resources and provide isolation. Sessions and secrets belong to spaces, while users and roles are global. Access is controlled through role bindings that specify which users have which roles in which spaces.

Obtaining a Token

POST /api/v0/auth/login
Content-Type: application/json

{
  "user": "admin",
  "pass": "your-password"
}

Response:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_at": "2025-01-02T12:00:00Z"
}

Using the Token

Include the token in the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

API Endpoints

Core Endpoints

Endpoint	Method	Description
/health	GET	Health check
/version	GET	API version info
/auth/login	POST	Authenticate and get token
/auth/me	GET	Get current user info

Service Accounts

Endpoint	Method	Description
/service-accounts	GET	List all service accounts
/service-accounts	POST	Create new service account
/service-accounts/{id}	GET	Get specific service account
/service-accounts/{id}	PUT	Update service account
/service-accounts/{id}	DELETE	Delete service account
/service-accounts/{id}/password	PUT	Update service account password

Roles

Endpoint	Method	Description
/roles	GET	List all roles
/roles	POST	Create new role
/roles/{id}	GET	Get specific role
/roles/{id}	DELETE	Delete role

Role Bindings

Endpoint	Method	Description
/role-bindings	GET	List all role bindings
/role-bindings	POST	Create new role binding
/role-bindings/{id}	GET	Get specific role binding
/role-bindings/{id}	DELETE	Delete role binding

Spaces

Endpoint	Method	Description
/spaces	GET	List all spaces
/spaces	POST	Create new space
/spaces/{name}	GET	Get specific space
/spaces/{name}	PUT	Update space
/spaces/{name}	DELETE	Delete space

Space Secrets

Endpoint	Method	Description
/spaces/{name}/secrets	GET	List space secrets
/spaces/{name}/secrets	POST	Create new secret
/spaces/{name}/secrets/{key}	GET	Get specific secret
/spaces/{name}/secrets/{key}	PUT	Update secret
/spaces/{name}/secrets/{key}	DELETE	Delete secret

Space Agents

Endpoint	Method	Description
/spaces/{name}/agents	GET	List space agents
/spaces/{name}/agents	POST	Create new agent

Space Builds

Endpoint	Method	Description
/spaces/{name}/build	POST	Trigger space build
/spaces/{name}/build/latest	GET	Get latest build status
/spaces/{name}/build/{build_id}	GET	Get specific build status

Sessions

Endpoint	Method	Description
/sessions	GET	List sessions
/sessions	POST	Create new session
/sessions/{id}	GET	Get specific session
/sessions/{id}	PUT	Update session details
/sessions/{id}/state	PUT	Update session state
/sessions/{id}/pause	POST	Pause session
/sessions/{id}/suspend	POST	Suspend session
/sessions/{id}/resume	POST	Resume session
/sessions/{id}/remix	POST	Fork session
/sessions/{id}	DELETE	Delete session

Session Messages

Endpoint	Method	Description
/sessions/{id}/messages	GET	List session messages
/sessions/{id}/messages	POST	Send message to session
/sessions/{id}/messages/count	GET	Get message count
/sessions/{id}/messages	DELETE	Clear all messages

Agents

Endpoint	Method	Description
/spaces/{name}/agents/{agent_name}	GET	Get specific agent
/spaces/{name}/agents/{agent_name}	PUT	Update agent
/spaces/{name}/agents/{agent_name}	DELETE	Delete agent
/spaces/{name}/agents/{agent_name}/status	PATCH	Update agent status
/spaces/{name}/agents/{agent_name}/deploy	POST	Deploy agent
/spaces/{name}/agents/{agent_name}/stop	POST	Stop agent
/spaces/{name}/agents/running	GET	List running agents
/spaces/{name}/agents/{agent_name}/logs	GET	Get agent logs

Request Format

Headers

Required headers for authenticated requests:

Authorization: Bearer <token>
Content-Type: application/json

Request Body

All POST and PUT requests accept JSON:

{
  "field1": "value1",
  "field2": "value2"
}

Response Format

Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "example",
  "created_at": "2025-01-01T00:00:00Z"
}

Error Response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
500	Internal Server Error

Rate Limiting

Currently, Raworc does not enforce rate limiting, but this may change in future versions. Best practices:

• Cache responses when possible
• Use pagination for list operations
• Implement exponential backoff for retries

Pagination

List endpoints support pagination:

GET /sessions?limit=20&offset=0
GET /service-accounts?limit=50&offset=100
GET /spaces?limit=10&offset=0

Parameters:

• limit - Maximum number of items to return (default: 100, max: 1000)
• offset - Number of items to skip (default: 0)

Response Headers:

X-Total-Count: 250
X-Page-Offset: 100
X-Page-Limit: 50

Filtering

Some endpoints support filtering:

GET /sessions?workspace_name=my-project  # Sessions for workspace
GET /sessions?state=IDLE
GET /spaces?active=true
GET /spaces/{name}/secrets?show_values=true

SDK Support

Official SDKs are planned for:

• Python
• JavaScript/TypeScript
• Go
• Rust

Webhooks

Webhook support is planned for future releases to enable:

• Real-time notifications
• Event-driven workflows
• Third-party integrations

API Versioning

The API uses URL versioning:

• Current version: v0
• Format: /api/v{version}/endpoint

Breaking changes will result in a new API version.

Best Practices

1. Use Specific Fields: Only request/send needed fields
2. Handle Errors: Implement proper error handling
3. Validate Input: Validate data before sending
4. Use HTTPS: Always use HTTPS in production
5. Token Management: Refresh tokens before expiry
6. Idempotency: Make requests idempotent where possible

Available API Documentation

• REST API Reference - HTTP REST API documentation (updated with correct base URLs)

Next Steps

• Explore the REST API Reference for detailed endpoint documentation
• Review RBAC Permissions for API access control