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 |