{
  "openapi": "3.0.3",
  "info": {
    "title": "LiteLLM Agent Platform API",
    "description": "Unified API for the LiteLLM Agent Platform — gateway, agents, sessions, and runtimes.",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://litellm-rust.onrender.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:4000",
      "description": "Local (Docker Compose)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "System"
    },
    {
      "name": "Models"
    },
    {
      "name": "Messages"
    },
    {
      "name": "API Keys"
    },
    {
      "name": "Agents"
    },
    {
      "name": "Sessions"
    },
    {
      "name": "Runtimes"
    },
    {
      "name": "MCP"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Health check",
        "tags": [
          "System"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "summary": "List gateway capabilities",
        "tags": [
          "System"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Providers, endpoints, MCP servers, and agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "anthropic",
                        "openai"
                      ]
                    },
                    "mcp_servers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "runtimes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "local-opencode",
                        "cursor"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing gateway key"
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List configured model aliases",
        "tags": [
          "Models"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "runtime",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional runtime alias. When set, returns models available for that runtime."
          }
        ],
        "responses": {
          "200": {
            "description": "OpenAI-compatible model list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "example": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "example": "anthropic/*"
                          },
                          "object": {
                            "type": "string",
                            "example": "model"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing gateway key"
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "operationId": "createMessage",
        "summary": "Create a message (Anthropic-compatible)",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages",
                  "max_tokens"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Model alias from config. Available: anthropic/*, gpt-5.5",
                    "example": "anthropic/*"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    },
                    "example": [
                      {
                        "role": "user",
                        "content": "Hello!"
                      }
                    ]
                  },
                  "max_tokens": {
                    "type": "integer",
                    "example": 1024
                  },
                  "stream": {
                    "type": "boolean",
                    "example": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message response from upstream provider",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "example": "message"
                    },
                    "role": {
                      "type": "string",
                      "example": "assistant"
                    },
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "example": "text"
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "model": {
                      "type": "string"
                    },
                    "stop_reason": {
                      "type": "string",
                      "example": "end_turn"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "input_tokens": {
                          "type": "integer"
                        },
                        "output_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing master key"
          },
          "404": {
            "description": "Model not found in config"
          }
        }
      }
    },
    "/api/keys": {
      "get": {
        "operationId": "listGatewayApiKeys",
        "summary": "List gateway API keys",
        "tags": [
          "API Keys"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "API key metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing gateway key"
          }
        }
      },
      "post": {
        "operationId": "createGatewayApiKey",
        "summary": "Create a gateway API key",
        "tags": [
          "API Keys"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "example": "alice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The secret is returned once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string",
                      "description": "The secret value — shown once, store it now."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing gateway key"
          }
        }
      }
    },
    "/api/keys/{id}": {
      "delete": {
        "operationId": "deleteGatewayApiKey",
        "summary": "Delete a gateway API key",
        "tags": [
          "API Keys"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Invalid or missing gateway key"
          },
          "404": {
            "description": "API key not found"
          }
        }
      }
    },
    "/api/agent-runtimes": {
      "get": {
        "operationId": "listAgentRuntimes",
        "summary": "List built-in agent runtimes",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Built-in runtime catalog and credential status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRuntimesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/agent-runtimes/{runtime}/credentials": {
      "put": {
        "operationId": "saveAgentRuntimeCredential",
        "summary": "Save credentials for a built-in runtime",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "runtime",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "claude_managed_agents",
                "cursor",
                "gemini_antigravity",
                "elastic_agent_builder"
              ]
            },
            "example": "cursor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SaveRuntimeCredentialRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credential saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRuntimesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "delete": {
        "operationId": "deleteAgentRuntimeCredential",
        "summary": "Delete credentials for a built-in runtime",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "runtime",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "claude_managed_agents",
                "cursor",
                "gemini_antigravity",
                "elastic_agent_builder"
              ]
            },
            "example": "cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Credential deleted"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/runtime-harnesses": {
      "get": {
        "operationId": "listRuntimeHarnesses",
        "summary": "List registered runtime harnesses",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of registered runtimes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RuntimeHarnessesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "createRuntimeHarness",
        "summary": "Register a runtime harness",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateRuntimeHarnessRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Runtime registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RuntimeHarnessesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/runtime-harnesses/{alias}": {
      "put": {
        "operationId": "updateRuntimeHarness",
        "summary": "Update a runtime harness",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "alias",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cursor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRuntimeHarnessRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RuntimeHarnessesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Harness not found"
          }
        }
      },
      "delete": {
        "operationId": "deleteRuntimeHarness",
        "summary": "Delete a runtime harness",
        "tags": [
          "Runtimes"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "alias",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Harness not found"
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "List agents",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of agents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "createAgent",
        "summary": "Create an agent",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/agents/{agent_id}": {
      "get": {
        "operationId": "getAgent",
        "summary": "Get an agent",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Agent not found"
          }
        }
      },
      "patch": {
        "operationId": "updateAgent",
        "summary": "Update an agent",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Agent not found"
          }
        }
      },
      "delete": {
        "operationId": "deleteAgent",
        "summary": "Delete an agent",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Agent not found"
          }
        }
      }
    },
    "/session": {
      "post": {
        "operationId": "createSession",
        "summary": "Create a session",
        "tags": [
          "Sessions"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/session/{session_id}/prompt_async": {
      "post": {
        "operationId": "sendSessionPrompt",
        "summary": "Queue a prompt for a session",
        "tags": [
          "Sessions"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptRequest"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Prompt queued"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Session not found"
          }
        }
      }
    },
    "/v1/sessions/{session_id}/events": {
      "get": {
        "operationId": "listSessionEvents",
        "summary": "List session events",
        "tags": [
          "Sessions"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "API key alternative to the Authorization header."
          }
        ],
        "responses": {
          "200": {
            "description": "Stored or provider-backed runtime events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AgentEvent"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Session not found"
          }
        }
      }
    },
    "/v1/sessions/{session_id}/events/stream": {
      "get": {
        "operationId": "streamSessionEvents",
        "summary": "Stream session events (SSE)",
        "tags": [
          "Sessions"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "API key (alternative to Authorization header, required for EventSource)"
          }
        ],
        "responses": {
          "200": {
            "description": "Server-sent event stream. Events are newline-delimited JSON prefixed with `data: `.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Session not found"
          }
        }
      }
    },
    "/mcp/{server_id}": {
      "post": {
        "operationId": "mcpProxy",
        "summary": "Proxy to a named MCP server",
        "tags": [
          "MCP"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Server name as configured in config.yaml `mcp_servers` block",
            "example": "github"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "example": "tools/list"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP server response"
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "MCP server not configured"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your LITELLM_MASTER_KEY. Default for local Docker Compose: `sk-local`"
      }
    },
    "schemas": {
      "RuntimeHarness": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "example": "local-opencode"
          },
          "api_spec": {
            "type": "string",
            "enum": [
              "claude_managed_agents",
              "cursor",
              "gemini_antigravity",
              "elastic_agent_builder"
            ],
            "example": "claude_managed_agents"
          },
          "display_name": {
            "type": "string",
            "example": "local-opencode"
          },
          "api_base": {
            "type": "string",
            "example": "http://opencode:8080"
          },
          "is_default": {
            "type": "boolean"
          },
          "connected": {
            "type": "boolean"
          },
          "masked_api_key": {
            "type": "string",
            "nullable": true
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "RuntimeHarnessesResponse": {
        "type": "object",
        "properties": {
          "harnesses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RuntimeHarness"
            }
          }
        }
      },
      "AgentRuntime": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "claude_managed_agents",
              "cursor",
              "gemini_antigravity",
              "elastic_agent_builder"
            ]
          },
          "name": {
            "type": "string",
            "example": "Cursor"
          },
          "default_api_base": {
            "type": "string",
            "example": "https://api.cursor.com"
          },
          "credential_provider_id": {
            "type": "string",
            "example": "cursor"
          },
          "credential_provider_name": {
            "type": "string",
            "example": "Cursor"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "connected": {
            "type": "boolean"
          },
          "api_base": {
            "type": "string",
            "nullable": true
          },
          "masked_api_key": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AgentRuntimesResponse": {
        "type": "object",
        "properties": {
          "runtimes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentRuntime"
            }
          }
        }
      },
      "SaveRuntimeCredentialRequest": {
        "type": "object",
        "required": [
          "api_key"
        ],
        "properties": {
          "api_key": {
            "type": "string",
            "example": "sk-..."
          },
          "api_base": {
            "type": "string",
            "description": "Optional. Defaults to the runtime's built-in base URL when omitted.",
            "example": "https://api.cursor.com"
          }
        }
      },
      "CreateRuntimeHarnessRequest": {
        "type": "object",
        "required": [
          "alias",
          "api_spec",
          "api_base",
          "api_key"
        ],
        "properties": {
          "alias": {
            "type": "string",
            "example": "local-opencode"
          },
          "api_spec": {
            "type": "string",
            "enum": [
              "claude_managed_agents",
              "cursor",
              "gemini_antigravity",
              "elastic_agent_builder"
            ],
            "example": "claude_managed_agents"
          },
          "api_base": {
            "type": "string",
            "example": "http://opencode:8080"
          },
          "api_key": {
            "type": "string",
            "example": "local-opencode-key"
          }
        }
      },
      "UpdateRuntimeHarnessRequest": {
        "type": "object",
        "properties": {
          "api_base": {
            "type": "string",
            "example": "http://opencode:8080"
          },
          "api_key": {
            "type": "string",
            "example": "local-opencode-key"
          }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "example": "my-agent"
          },
          "model": {
            "type": "string",
            "example": "claude-opus-4-5"
          },
          "system": {
            "type": "string"
          },
          "tools": {
            "type": "object"
          },
          "config": {
            "type": "object",
            "description": "Runtime-specific config. For runtime-backed agents this usually includes `runtime`."
          },
          "owner_id": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "example": "paused"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "harness": {
            "type": "string",
            "example": "claude-code"
          },
          "created_at": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "AgentsResponse": {
        "type": "object",
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Agent"
            }
          }
        }
      },
      "CreateAgentRequest": {
        "type": "object",
        "required": [
          "name",
          "owner_id"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "my-agent"
          },
          "owner_id": {
            "type": "string",
            "example": "local-user"
          },
          "runtime": {
            "type": "string",
            "example": "cursor",
            "description": "Built-in runtime ID or registered runtime harness alias. Stored in agent config."
          },
          "model": {
            "type": "string",
            "example": "claude-opus-4-5"
          },
          "system": {
            "type": "string",
            "example": "You are a helpful assistant."
          },
          "description": {
            "type": "string"
          },
          "prompt": {
            "type": "string",
            "description": "Fallback system prompt when `system` is omitted."
          },
          "config": {
            "type": "object"
          },
          "tools": {
            "description": "Runtime tool definitions.",
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              {
                "type": "object"
              }
            ]
          }
        }
      },
      "Session": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "agent": {
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "harness": {
            "type": "string"
          },
          "runtime": {
            "type": "string"
          },
          "runtime_agent_ref_id": {
            "type": "string",
            "nullable": true
          },
          "provider_session_id": {
            "type": "string",
            "nullable": true
          },
          "provider_run_id": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "idle",
              "error"
            ],
            "example": "idle"
          },
          "environment": {
            "type": "object"
          },
          "time": {
            "type": "object",
            "properties": {
              "created": {
                "type": "integer",
                "format": "int64"
              },
              "updated": {
                "type": "integer",
                "format": "int64",
                "nullable": true
              }
            }
          }
        }
      },
      "CreateSessionRequest": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "agent": {
            "type": "string",
            "description": "Agent ID or configured harness ID. For local DB agents, use `agent_id` or `agent`."
          },
          "agent_id": {
            "type": "string"
          },
          "harness": {
            "type": "string"
          },
          "runtime": {
            "type": "string",
            "description": "Built-in runtime ID or runtime harness alias. When present, creates a runtime-backed session.",
            "example": "cursor"
          },
          "prompt": {
            "type": "string",
            "description": "Optional initial prompt. If present, the runtime session starts immediately."
          },
          "environment": {
            "type": "object",
            "description": "Runtime-specific environment settings",
            "properties": {
              "repository": {
                "type": "string",
                "example": "https://github.com/your-org/your-repo"
              },
              "ref": {
                "type": "string",
                "example": "main"
              },
              "auto_create_pr": {
                "type": "boolean",
                "default": false
              }
            }
          },
          "timezone": {
            "type": "string",
            "example": "America/Los_Angeles"
          },
          "tz": {
            "type": "string",
            "example": "America/Los_Angeles"
          }
        }
      },
      "PromptRequest": {
        "type": "object",
        "required": [
          "model",
          "parts"
        ],
        "properties": {
          "model": {
            "type": "object",
            "required": [
              "modelID"
            ],
            "properties": {
              "modelID": {
                "type": "string",
                "example": "claude-opus-4-5"
              }
            }
          },
          "parts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "type",
                "text"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "text"
                  ],
                  "example": "text"
                },
                "text": {
                  "type": "string",
                  "example": "Summarize the repo README."
                }
              }
            }
          }
        }
      },
      "AgentEvent": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "session.status_running",
              "agent.message",
              "agent.tool_use",
              "agent.tool_result",
              "session.status_idle",
              "session.error"
            ],
            "example": "agent.message"
          },
          "content": {
            "type": "string",
            "example": "Here is the summary..."
          }
        }
      }
    }
  }
}