{
  "openapi": "3.1.0",
  "info": {
    "title": "Cody API",
    "version": "1.0.0",
    "description": "Send events to your Cody agents programmatically and poll their results. Each API key belongs to one account; requests are routed to that account's dedicated Cody instance and never touch another customer's data.",
    "contact": { "name": "Cody", "url": "https://heycody.ink/docs", "email": "cody@heycody.ink" }
  },
  "servers": [{ "url": "https://api.heycody.ink", "description": "Production" }],
  "security": [{ "bearerAuth": [] }],
  "tags": [{ "name": "Runs", "description": "Start agent runs and poll their status." }],
  "paths": {
    "/codyapi": {
      "post": {
        "tags": ["Runs"],
        "operationId": "sendEvent",
        "summary": "Send an event",
        "description": "Starts an isolated agent run. Returns immediately with a runId you can poll.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SendEventRequest" },
              "example": { "agentId": "n1774177363529", "message": "Summarize today's new leads" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run accepted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SendEventResponse" },
                "example": { "ok": true, "runId": "2cb88653-7005-4062-9232-d0982ed2c1e3", "agentId": "n1774177363529", "status": "in_flight" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      },
      "get": {
        "tags": ["Runs"],
        "operationId": "getAgentsOrStatus",
        "summary": "List agents / Run status",
        "description": "Two read actions selected by the `action` query parameter:\n\n- `action=agents` — list your agent ids and names.\n- `action=status` — poll a run (requires `runId`).",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "description": "Which read action to perform.",
            "schema": { "type": "string", "enum": ["agents", "status"] }
          },
          {
            "name": "runId",
            "in": "query",
            "required": false,
            "description": "Required when `action=status`. The runId returned by POST /codyapi.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Agents list (action=agents) or run status (action=status).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/AgentsResponse" },
                    { "$ref": "#/components/schemas/RunStatusResponse" }
                  ]
                },
                "examples": {
                  "agents": {
                    "summary": "action=agents",
                    "value": { "ok": true, "agents": [{ "id": "main", "name": "Cody" }, { "id": "n1774177363529", "name": "Coby" }] }
                  },
                  "status": {
                    "summary": "action=status",
                    "value": { "ok": true, "run": { "runId": "2cb88653-…", "status": "succeeded", "durationMs": 5013, "endedAtMs": 1784391347949 } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A secret API key (cody_sk_…) generated in the dashboard under Tools → Cody API. Send it as `Authorization: Bearer <key>`."
      }
    },
    "responses": {
      "Error": {
        "description": "Error. Non-2xx status with a JSON body.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": { "ok": false, "error": "Missing or malformed API key." }
          }
        }
      }
    },
    "schemas": {
      "SendEventRequest": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": { "type": "string", "description": "The task or message for the agent." },
          "agentId": { "type": "string", "description": "Target a specific agent. Omit to use your default agent. Get valid ids from `GET /codyapi?action=agents`." },
          "name": { "type": "string", "description": "A label for the run, shown in your event log." },
          "deliver": { "type": "boolean", "default": false, "description": "If true, the agent also delivers its reply to its configured channel." },
          "timeoutSeconds": { "type": "number", "description": "Maximum seconds the run may take before timing out." }
        }
      },
      "SendEventResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "runId": { "type": "string", "description": "Poll this with `GET /codyapi?action=status&runId=…`." },
          "agentId": { "type": "string" },
          "status": { "type": "string", "enum": ["in_flight"] }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        }
      },
      "AgentsResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }
        }
      },
      "RunStatus": {
        "type": "object",
        "properties": {
          "runId": { "type": "string" },
          "status": { "type": "string", "enum": ["in_flight", "succeeded", "failed", "unknown"] },
          "durationMs": { "type": "integer" },
          "endedAtMs": { "type": "integer" },
          "error": { "type": "string" }
        }
      },
      "RunStatusResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "run": { "$ref": "#/components/schemas/RunStatus" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "enum": [false] },
          "error": { "type": "string" }
        }
      }
    }
  }
}