Skip to content

api.md

Latest commit

 

History

History
260 lines (203 loc) · 5.14 KB

api.md

File metadata and controls

260 lines (203 loc) · 5.14 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"
}

Providers

GET /agents/providers

List available providers with installation status.

Response: Array of provider objects

[
  {
    "name": "kiro_cli",
    "binary": "kiro-cli",
    "installed": true
  },
  {
    "name": "claude_code",
    "binary": "claude",
    "installed": true
  },
  {
    "name": "q_cli",
    "binary": "q",
    "installed": false
  },
  {
    "name": "codex",
    "binary": "codex",
    "installed": true
  },
  {
    "name": "gemini_cli",
    "binary": "gemini",
    "installed": true
  },
  {
    "name": "kimi_cli",
    "binary": "kimi",
    "installed": false
  },
  {
    "name": "copilot_cli",
    "binary": "copilot",
    "installed": false
  }
]

Note: The installed field checks if the provider binary is available in the system PATH via shutil.which().

Sessions

POST /sessions

Create a new session with one terminal.

Parameters:

  • provider (string, required): Provider type ("kiro_cli", "claude_code", "codex", "gemini_cli", "kimi_cli", "copilot_cli", or "q_cli")
  • agent_profile (string, required): Agent profile name
  • session_name (string, optional): Custom session name
  • working_directory (string, optional): Working directory for the agent session

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
  • working_directory (string, optional): Working directory for the terminal

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": "kiro_cli|claude_code|codex|gemini_cli|kimi_cli|copilot_cli|q_cli",
  "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"
}

GET /terminals/{terminal_id}/working-directory

Get the current working directory of a terminal's pane.

Response:

{
  "working_directory": "/home/user/project"
}

Note: Returns null if working directory is unavailable.

POST /terminals/{terminal_id}/exit

Send provider-specific exit command to terminal.

Behavior:

  • Calls the provider's exit_cli() method to get the exit command
  • Text commands (e.g., /exit, quit) are sent as literal text via send_input()
  • Key sequences prefixed with C- or M- (e.g., C-d for Ctrl+D) are sent as tmux key sequences via send_special_key(), which tmux interprets as actual key presses
Provider Exit Command Type
kiro_cli /exit Text
claude_code /exit Text
codex /exit Text
gemini_cli /exit Text
kimi_cli /exit Text
copilot_cli /exit Text
q_cli /exit Text

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"
}