❯Cmd+Ctrl

Appearance

API Reference ​

The Cmd+Ctrl API allows programmatic access to sessions, devices, and messages.

Base URL ​

https://api.cmd-ctrl.ai

Authentication ​

All API requests require authentication via JWT bearer token.

bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.cmd-ctrl.ai/api/sessions

Tokens are obtained through the OAuth flow in the web application.

Endpoints ​

Health Check ​

GET /health

Returns server health status. No authentication required.

Response:

json
{
  "status": "ok",
  "version": "1.0.0"
}

Sessions ​

List Sessions ​

GET /api/sessions

Returns all sessions for the authenticated user.

Response:

json
{
  "sessions": [
    {
      "id": "device123:claude_code:session456",
      "title": "Fix authentication bug",
      "status": "active",
      "agentType": "claude_code",
      "deviceId": "device123",
      "projectPath": "/Users/me/projects/myapp",
      "createdAt": "2025-01-19T12:00:00Z",
      "updatedAt": "2025-01-19T12:30:00Z"
    }
  ]
}

Get Session ​

GET /api/sessions/:id

Returns a single session with recent messages.

Create Session ​

POST /api/sessions

Request Body:

json
{
  "deviceId": "device123",
  "projectPath": "/Users/me/projects/myapp",
  "message": "Look at this project and explain what it does"
}

Send Message ​

POST /api/sessions/:id/messages

Request Body:

json
{
  "content": "Now add a README file"
}

Devices ​

List Devices ​

GET /api/devices

Returns all registered devices for the authenticated user.

Response:

json
{
  "devices": [
    {
      "id": "device123",
      "name": "MacBook Pro",
      "hostname": "macbook-pro.local",
      "agentType": "claude_code",
      "status": "online",
      "lastSeenAt": "2025-01-19T12:30:00Z"
    }
  ]
}

Watched Sessions ​

List Watched Sessions ​

GET /api/watched-sessions

Returns session IDs the user is watching for notifications.

Watch Session ​

POST /api/watched-sessions

Request Body:

json
{
  "sessionId": "device123:claude_code:session456"
}

Unwatch Session ​

DELETE /api/watched-sessions

Request Body:

json
{
  "sessionId": "device123:claude_code:session456"
}

WebSocket API ​

Real-time updates are delivered via WebSocket.

Client Connection ​

wss://api.cmd-ctrl.ai/ws/attention

Connect with your JWT token in the Authorization header or as a query parameter.

Message Types ​

Messages are JSON objects with a type field:

json
{"type": "session_update", "session": {...}}
{"type": "new_message", "sessionId": "...", "message": {...}}
{"type": "device_status", "deviceId": "...", "status": "online"}

Error Responses ​

All errors return a JSON object:

json
{
  "error": "Not found",
  "code": "SESSION_NOT_FOUND",
  "status": 404
}

Common status codes:

  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (missing or invalid token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not found
  • 500 - Internal server error

Rate Limits ​

API requests are rate limited to:

  • 100 requests per minute for most endpoints
  • 10 requests per minute for session creation

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705670400