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

CodeDescription
AUTH_REQUIREDAuthentication is required
INVALID_TENANTInvalid or missing tenant ID
RATE_LIMITEDToo many requests
AGENT_NOT_FOUNDAgent does not exist