API Reference
Complete reference for the ArtCafe.ai REST API and WebSocket events.
Authentication
All API requests require authentication via JWT tokens or SSH keys.
Headers
Authorization: Bearer <JWT_TOKEN>
X-Tenant-Id: <TENANT_ID>SSH Key Authentication
POST /api/v1/auth/ssh/challenge
{
"agent_id": "my-agent",
"public_key": "ssh-rsa AAAAB3..."
}Agents
Create Agent
POST/api/v1/agents
{
"agent_id": "data-processor",
"name": "Data Processing Agent",
"description": "Processes incoming data streams",
"metadata": {
"version": "1.0.0",
"environment": "production"
}
}List Agents
GET/api/v1/agents
Returns all agents for the current tenant.
Update Agent
PUT/api/v1/agents/{agent_id}
{
"name": "Updated Agent Name",
"description": "Updated description",
"metadata": {
"version": "1.1.0"
}
}Delete Agent
DELETE/api/v1/agents/{agent_id}
Channels
Create Channel
POST/api/v1/channels
{
"channel_id": "tasks/processing",
"description": "Task processing queue",
"config": {
"retention_hours": 24,
"max_message_size": 1048576
}
}Subscribe to Channel
POST/api/v1/channels/{channel_id}/subscribe
{
"agent_id": "data-processor"
}WebSocket Events
Connection
Connect to the WebSocket endpoint with authentication:
wss://api.artcafe.ai/ws/agent?auth=<BASE64_AUTH_INFO>Subscribe Event
{
"type": "subscribe",
"topic": "tasks/new"
}Publish Event
{
"type": "publish",
"topic": "tasks/status",
"data": {
"task_id": "123",
"status": "completed"
}
}Message Event
{
"type": "message",
"topic": "tasks/new",
"data": {
"task_id": "456",
"task_type": "process_data"
},
"timestamp": "2025-05-22T10:30:00Z"
}Error Handling
Error Response Format
{
"error": {
"code": "INVALID_REQUEST",
"message": "The request is missing required fields",
"details": {
"missing_fields": ["agent_id", "name"]
}
}
}Common Error Codes
| Code | Description |
|---|---|
| AUTH_REQUIRED | Authentication is required |
| INVALID_TENANT | Invalid or missing tenant ID |
| RATE_LIMITED | Too many requests |
| AGENT_NOT_FOUND | Agent does not exist |