Skip to content

api.md

Latest commit

 

History

History
182 lines (134 loc) · 3.23 KB

api.md

File metadata and controls

182 lines (134 loc) · 3.23 KB

CLI Agent Orchestrator API Documentation

Base URL: http://localhost:9889 (default)

Health Check

GET /health

Check if the server is running.

Response:

{
  "status": "ok",
  "service": "cli-agent-orchestrator"
}

Sessions

POST /sessions

Create a new session with one terminal.

Parameters:

  • provider (string, required): Provider type ("q_cli" or "claude_code")
  • agent_profile (string, required): Agent profile name
  • session_name (string, optional): Custom session name

Response: Terminal object (201 Created)

GET /sessions

List all sessions.

Response: Array of session objects

GET /sessions/{session_name}

Get details of a specific session.

Response: Session object with terminals list

DELETE /sessions/{session_name}

Delete a session and all its terminals.

Response:

{
  "success": true
}

Terminals

Note: All terminal_id path parameters must be 8-character hexadecimal strings (e.g., "a1b2c3d4").

POST /sessions/{session_name}/terminals

Create an additional terminal in an existing session.

Parameters:

  • provider (string, required): Provider type
  • agent_profile (string, required): Agent profile name

Response: Terminal object (201 Created)

GET /sessions/{session_name}/terminals

List all terminals in a session.

Response: Array of terminal objects

GET /terminals/{terminal_id}

Get terminal details.

Response: Terminal object

{
  "id": "string",
  "name": "string",
  "provider": "q_cli|claude_code",
  "session_name": "string",
  "agent_profile": "string",
  "status": "idle|processing|completed|waiting_user_answer|error",
  "last_active": "timestamp"
}

POST /terminals/{terminal_id}/input

Send input to a terminal.

Parameters:

  • message (string, required): Message to send

Response:

{
  "success": true
}

GET /terminals/{terminal_id}/output

Get terminal output.

Parameters:

  • mode (string, optional): Output mode - "full" (default), "last", or "tail"

Response:

{
  "output": "string",
  "mode": "string"
}

POST /terminals/{terminal_id}/exit

Send provider-specific exit command to terminal.

Response:

{
  "success": true
}

DELETE /terminals/{terminal_id}

Delete a terminal.

Response:

{
  "success": true
}

Inbox (Terminal-to-Terminal Messaging)

POST /terminals/{receiver_id}/inbox/messages

Send a message to another terminal's inbox.

Parameters:

  • sender_id (string, required): Sender terminal ID
  • message (string, required): Message content

Response:

{
  "success": true,
  "message_id": "string",
  "sender_id": "string",
  "receiver_id": "string",
  "created_at": "timestamp"
}

Behavior:

  • Messages are queued and delivered when the receiver terminal is IDLE
  • Messages are delivered in order (oldest first)
  • Delivery is automatic via watchdog file monitoring

Error Responses

All endpoints return standard HTTP status codes:

  • 200 OK: Success
  • 201 Created: Resource created
  • 400 Bad Request: Invalid parameters
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error

Error response format:

{
  "detail": "Error message"
}
⚡