{
  "openapi": "3.1.0",
  "info": {
    "title": "Cork HTTP API",
    "version": "1.0.0",
    "description": "The HTTP API behind Cork (https://corkcli.com): workspaces, repos, members, activity, the ledger, costs, messages between people and agents, notes, deferred work, and long-running jobs. Agents usually reach Cork through its MCP server (https://mcp.corkcli.com); this API is for SDKs, dashboards and integrations.\n\n## Versioning\nEvery route is served under `/api/v1/...`, and every response carries `API-Version: 1`. The unversioned `/api/...` paths are deprecated aliases of the same handlers: they keep working, and their responses carry a `Deprecation` header (RFC 9745) and `Link: <...>; rel=\"successor-version\"` naming the v1 path. Breaking changes only ship in a new major version; at least six months' notice, with a `Sunset` header (RFC 8594), comes before anything is removed. Policy: https://corkcli.com/docs/api/versioning\n\n## Authentication\n`Authorization: Bearer <token>`. A token is one of: an OAuth 2.1 access token (`cat_...`) from the authorization code flow with PKCE (S256) at https://mcp.corkcli.com (dynamic client registration, RFC 7591, at https://mcp.corkcli.com/register; scope `collide`; access tokens last 24 hours and are refreshed with `crt_...` refresh tokens); a machine credential written by `cork login` to `~/.cork/credentials.json`; or a dashboard sign-in token. See https://corkcli.com/auth.md\n\n## Rate limits\nREST routes (`/api/v1/...`) are limited per caller (per credential, or per client address when unauthenticated) by a token bucket of 600 requests that refills at 10 per second. Agent routes (memory, intents, messages, inbox) are held to the workspace's plan instead: Free 8 per second with a burst of 120, Team 60 per second with a burst of 600, Business unmetered. Responses carry `RateLimit-Policy` and `RateLimit` (draft-ietf-httpapi-ratelimit-headers) plus `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Over the limit the answer is `429 Too Many Requests` with `Retry-After` and an error with `code: rate_limited`. Usage reports (a session's token bill) are never rate-limited.\n\n## Idempotency\nSend `Idempotency-Key` (1 to 255 characters) on any POST, PUT, PATCH or DELETE. Keys are scoped to the authenticated caller and kept for 24 hours. A retry with the same key and the same request returns the first response again, with `Idempotent-Replayed: true`. The same key with a different method, path or body is refused with `422` (`code: idempotency_key_reused`); while the first request is still running a retry gets `409` (`code: idempotency_key_in_progress`) with `Retry-After`. Responses with a 5xx status are not stored, so a retry runs again. Unauthenticated requests ignore the header.\n\n## Async jobs\nLong operations (graph export of a large repo, the waste report over many weeks, clearing a repo's map or notes, waiting for messages, waiting for a repo's push turn) can run as jobs. Either `POST /api/v1/jobs` with an `operation`, or send `Prefer: respond-async` to the endpoint itself. Both answer `202 Accepted` with `Location: /api/v1/jobs/{job_id}` and `Retry-After`. Poll `GET /api/v1/jobs/{job_id}` until `status` is `succeeded`, `failed` or `cancelled`; the operation's own response is at `result_url`. `DELETE` cancels a job that has not finished. Jobs belong to the caller who made them and are kept for 24 hours.\n\n## Errors\nErrors are JSON with an `error` message; newer endpoints add a machine-readable `code` (`rate_limited`, `idempotency_key_reused`, `idempotency_key_in_progress`, `not_found`, `unauthorized`, `invalid_request`). Agent routes reached by their unversioned paths answer `200` with `ok: false` and a `reason` so that hooks fail open; under `/api/v1` they use real status codes.",
    "contact": {
      "name": "Cork support",
      "email": "kevin@lithometric.com",
      "url": "https://corkcli.com/support"
    },
    "termsOfService": "https://corkcli.com/terms"
  },
  "externalDocs": {
    "description": "REST API docs",
    "url": "https://corkcli.com/docs/api"
  },
  "servers": [
    {
      "url": "https://api.corkcli.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "oauth2": [
        "collide"
      ]
    },
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "service",
      "description": "Health and the hook builds the installer downloads"
    },
    {
      "name": "workspaces",
      "description": "The signed-in account, its workspaces, members and invites"
    },
    {
      "name": "repos",
      "description": "A repo's live activity, history, costs, sessions and search"
    },
    {
      "name": "messages",
      "description": "Messages between people and their teammates' agents"
    },
    {
      "name": "notes",
      "description": "Durable notes and decisions anchored to code"
    },
    {
      "name": "intents",
      "description": "Work in flight and work left unfinished"
    },
    {
      "name": "jobs",
      "description": "Long-running operations: 202, poll, result, cancel"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "service"
        ],
        "summary": "Service health",
        "security": [],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          }
        }
      }
    },
    "/api/v1/status": {
      "get": {
        "operationId": "getServerStatus",
        "tags": [
          "service"
        ],
        "summary": "The server's own status record: its once-a-minute self-checks, 90 days of history and incidents",
        "description": "No credential. The status page's JSON (`/status.json` on corkcli.com) is the same shape with the website's own probes merged in; prefer it.",
        "security": [],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Status"
                }
              }
            },
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          }
        }
      }
    },
    "/status.json": {
      "servers": [
        {
          "url": "https://corkcli.com",
          "description": "The website"
        }
      ],
      "get": {
        "operationId": "getStatus",
        "tags": [
          "service"
        ],
        "summary": "Cork's status: overall indicator, each component with its checks and uptime since checks began, and incidents",
        "description": "No credential. Checked from two vantage points: the server's recorded self-checks and the website's live probes (cached up to 45 s). Answers 200 even when the server is unreachable, with `server.reachable: false` and a `server.note`. Also as Markdown at /status.md, and incidents as Atom at /status/feed.xml.",
        "security": [],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Status"
                }
              }
            }
          }
        }
      }
    },
    "/artifacts/hooks": {
      "get": {
        "operationId": "listHookBuilds",
        "tags": [
          "service"
        ],
        "summary": "The signed hook builds available for each platform",
        "security": [],
        "responses": {
          "200": {
            "description": "Build index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/invites/{code}": {
      "get": {
        "operationId": "previewInvite",
        "tags": [
          "workspaces"
        ],
        "summary": "Preview a workspace invite before joining",
        "security": [],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{8}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The invite",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "workspaces"
        ],
        "summary": "The signed-in account",
        "responses": {
          "200": {
            "description": "The account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/workspaces": {
      "get": {
        "operationId": "listWorkspaces",
        "tags": [
          "workspaces"
        ],
        "summary": "Workspaces the signed-in person belongs to",
        "responses": {
          "200": {
            "description": "Workspaces",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceList"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/workspaces/{workspace_id}/repos": {
      "get": {
        "operationId": "listRepos",
        "tags": [
          "repos"
        ],
        "summary": "Repos in a workspace",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id"
          }
        ],
        "responses": {
          "200": {
            "description": "Repos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepoList"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/workspaces/{workspace_id}/members": {
      "get": {
        "operationId": "listMembers",
        "tags": [
          "workspaces"
        ],
        "summary": "Members of a workspace and their seats",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id"
          }
        ],
        "responses": {
          "200": {
            "description": "Members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/workspaces/{workspace_id}/messages": {
      "get": {
        "operationId": "listMessages",
        "tags": [
          "messages"
        ],
        "summary": "A repo's message thread between people and agents, oldest first",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id"
          },
          {
            "name": "repo",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id (e.g. github.com/acme/api)"
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Only messages after this epoch second"
          }
        ],
        "responses": {
          "200": {
            "description": "Messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageList"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "sendMessage",
        "tags": [
          "messages"
        ],
        "summary": "Message agents in a repo: everyone, one person's agents, or whoever works on a piece of code",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessage"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sent"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "description": "Too many messages at once; wait a few seconds",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/activity/{repo_id}": {
      "get": {
        "operationId": "getActivity",
        "tags": [
          "repos"
        ],
        "summary": "Who is working in a repo right now and what they are doing",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id, URL-encoded (e.g. github.com%2Facme%2Fapi)"
          },
          {
            "name": "workspace",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id the repo belongs to"
          }
        ],
        "responses": {
          "200": {
            "description": "Live activity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/ledger/{repo_id}": {
      "get": {
        "operationId": "listLedger",
        "tags": [
          "repos"
        ],
        "summary": "A repo's history, one page at a time (newest page first)",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id, URL-encoded (e.g. github.com%2Facme%2Fapi)"
          },
          {
            "name": "workspace",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id the repo belongs to"
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Cursor: only rows with a sequence number below this (the oldest seq of the previous page)"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of ledger rows",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerPage"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/costs/{repo_id}": {
      "get": {
        "operationId": "getCosts",
        "tags": [
          "repos"
        ],
        "summary": "Tokens and estimated spend by model, person and repo",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id, URL-encoded (e.g. github.com%2Facme%2Fapi)"
          },
          {
            "name": "workspace",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id the repo belongs to"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 7
            },
            "description": "Window in days"
          }
        ],
        "responses": {
          "200": {
            "description": "Costs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/journal/{repo_id}": {
      "get": {
        "operationId": "listSessions",
        "tags": [
          "repos"
        ],
        "summary": "Agent sessions: who ran, for how long, what they touched and cost",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id, URL-encoded (e.g. github.com%2Facme%2Fapi)"
          },
          {
            "name": "workspace",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id the repo belongs to"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 7
            },
            "description": "Window in days"
          }
        ],
        "responses": {
          "200": {
            "description": "Sessions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/search/{repo_id}": {
      "get": {
        "operationId": "searchHistory",
        "tags": [
          "repos"
        ],
        "summary": "Search a repo's history: edits, reasons and notes",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id, URL-encoded (e.g. github.com%2Facme%2Fapi)"
          },
          {
            "name": "workspace",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id the repo belongs to"
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matches",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            },
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/plans": {
      "get": {
        "operationId": "listPlans",
        "tags": [
          "service"
        ],
        "security": [],
        "summary": "Plans, the free tier, and how to get credentials (no sign-in needed)",
        "responses": {
          "200": {
            "description": "Plans and credential discovery",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plans"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/graph-export/{repo_id}": {
      "get": {
        "operationId": "exportGraph",
        "tags": [
          "repos",
          "jobs"
        ],
        "summary": "Export a repo's code graph; send Prefer: respond-async to run it as a job",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repo id, URL-encoded (e.g. github.com%2Facme%2Fapi)"
          },
          {
            "name": "workspace",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id the repo belongs to"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Export format"
          },
          {
            "$ref": "#/components/parameters/Prefer"
          }
        ],
        "responses": {
          "200": {
            "description": "The exported graph",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "202": {
            "description": "Accepted as a job: poll the Location header (also status_url in the body) until the job has succeeded, failed or been cancelled.",
            "headers": {
              "Location": {
                "description": "Where to poll the job: /api/v1/jobs/{job_id}.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/api/v1/jobs/job_8c1d2f"
                },
                "required": true
              },
              "Retry-After": {
                "description": "Seconds to wait before polling the job.",
                "schema": {
                  "type": "integer"
                },
                "required": true
              },
              "Preference-Applied": {
                "description": "`respond-async` when the Prefer header was honoured.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "The API's major version: 1.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A job the server accepted: poll status_url (the same address as the Location header) until its status is succeeded, failed or cancelled.",
                  "required": [
                    "job_id",
                    "status",
                    "status_url"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "description": "The job's id.",
                      "example": "job_8c1d2f"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running"
                      ],
                      "description": "Where the job is now; a new job is queued."
                    },
                    "poll_after_s": {
                      "type": "number",
                      "description": "Seconds to wait before polling.",
                      "example": 2
                    },
                    "status_url": {
                      "type": "string",
                      "format": "uri-reference",
                      "description": "Where to poll the job: /api/v1/jobs/{job_id}, the same as the Location header.",
                      "example": "/api/v1/jobs/job_8c1d2f"
                    }
                  }
                },
                "example": {
                  "job_id": "job_8c1d2f",
                  "status": "queued",
                  "poll_after_s": 2,
                  "status_url": "/api/v1/jobs/job_8c1d2f"
                }
              }
            },
            "links": {
              "GetJob": {
                "operationId": "getJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Poll the job."
              },
              "GetJobResult": {
                "operationId": "getJobResult",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "The operation's own status and body, once the job has finished."
              },
              "CancelJob": {
                "operationId": "cancelJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Cancel the job before it finishes."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/workspaces/{workspace_id}/waste": {
      "get": {
        "operationId": "getWasteReport",
        "tags": [
          "workspaces",
          "jobs"
        ],
        "summary": "What Cork prevented across the workspace's repos, week by week; Prefer: respond-async runs it as a job",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id"
          },
          {
            "name": "weeks",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Weeks to cover"
          },
          {
            "$ref": "#/components/parameters/Prefer"
          }
        ],
        "responses": {
          "200": {
            "description": "The report",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "202": {
            "description": "Accepted as a job: poll the Location header (also status_url in the body) until the job has succeeded, failed or been cancelled.",
            "headers": {
              "Location": {
                "description": "Where to poll the job: /api/v1/jobs/{job_id}.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/api/v1/jobs/job_8c1d2f"
                },
                "required": true
              },
              "Retry-After": {
                "description": "Seconds to wait before polling the job.",
                "schema": {
                  "type": "integer"
                },
                "required": true
              },
              "Preference-Applied": {
                "description": "`respond-async` when the Prefer header was honoured.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "The API's major version: 1.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A job the server accepted: poll status_url (the same address as the Location header) until its status is succeeded, failed or cancelled.",
                  "required": [
                    "job_id",
                    "status",
                    "status_url"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "description": "The job's id.",
                      "example": "job_8c1d2f"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running"
                      ],
                      "description": "Where the job is now; a new job is queued."
                    },
                    "poll_after_s": {
                      "type": "number",
                      "description": "Seconds to wait before polling.",
                      "example": 2
                    },
                    "status_url": {
                      "type": "string",
                      "format": "uri-reference",
                      "description": "Where to poll the job: /api/v1/jobs/{job_id}, the same as the Location header.",
                      "example": "/api/v1/jobs/job_8c1d2f"
                    }
                  }
                },
                "example": {
                  "job_id": "job_8c1d2f",
                  "status": "queued",
                  "poll_after_s": 2,
                  "status_url": "/api/v1/jobs/job_8c1d2f"
                }
              }
            },
            "links": {
              "GetJob": {
                "operationId": "getJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Poll the job."
              },
              "GetJobResult": {
                "operationId": "getJobResult",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "The operation's own status and body, once the job has finished."
              },
              "CancelJob": {
                "operationId": "cancelJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Cancel the job before it finishes."
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/workspaces/{workspace_id}/repos/clear": {
      "post": {
        "operationId": "clearRepoData",
        "tags": [
          "repos",
          "jobs"
        ],
        "summary": "Clear a repo's code map (rebuilt on next use) or its notes; owner only; Prefer: respond-async runs it as a job",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace id"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/Prefer"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "what": {
                    "type": "string",
                    "enum": [
                      "map",
                      "notes"
                    ]
                  }
                },
                "required": [
                  "repo_id",
                  "what"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cleared",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "202": {
            "description": "Accepted as a job: poll the Location header (also status_url in the body) until the job has succeeded, failed or been cancelled.",
            "headers": {
              "Location": {
                "description": "Where to poll the job: /api/v1/jobs/{job_id}.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/api/v1/jobs/job_8c1d2f"
                },
                "required": true
              },
              "Retry-After": {
                "description": "Seconds to wait before polling the job.",
                "schema": {
                  "type": "integer"
                },
                "required": true
              },
              "Preference-Applied": {
                "description": "`respond-async` when the Prefer header was honoured.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "The API's major version: 1.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A job the server accepted: poll status_url (the same address as the Location header) until its status is succeeded, failed or cancelled.",
                  "required": [
                    "job_id",
                    "status",
                    "status_url"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "description": "The job's id.",
                      "example": "job_8c1d2f"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running"
                      ],
                      "description": "Where the job is now; a new job is queued."
                    },
                    "poll_after_s": {
                      "type": "number",
                      "description": "Seconds to wait before polling.",
                      "example": 2
                    },
                    "status_url": {
                      "type": "string",
                      "format": "uri-reference",
                      "description": "Where to poll the job: /api/v1/jobs/{job_id}, the same as the Location header.",
                      "example": "/api/v1/jobs/job_8c1d2f"
                    }
                  }
                },
                "example": {
                  "job_id": "job_8c1d2f",
                  "status": "queued",
                  "poll_after_s": 2,
                  "status_url": "/api/v1/jobs/job_8c1d2f"
                }
              }
            },
            "links": {
              "GetJob": {
                "operationId": "getJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Poll the job."
              },
              "GetJobResult": {
                "operationId": "getJobResult",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "The operation's own status and body, once the job has finished."
              },
              "CancelJob": {
                "operationId": "cancelJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Cancel the job before it finishes."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/memory/save": {
      "post": {
        "operationId": "rememberNote",
        "tags": [
          "notes"
        ],
        "summary": "Save a durable team note or decision, optionally anchored to code (the MCP tool remember)",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "fact": {
                    "type": "string"
                  },
                  "anchor": {
                    "type": "string",
                    "description": "path::symbol, a file, or dir/"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "note",
                      "decision"
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "supersedes": {
                    "type": "string"
                  }
                },
                "required": [
                  "repo_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/memory/recall": {
      "post": {
        "operationId": "recallNotes",
        "tags": [
          "notes"
        ],
        "summary": "Search the team's saved notes by text and tags (the MCP tool recall)",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "query": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": [
                  "repo_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/intent/defer": {
      "post": {
        "operationId": "deferIntent",
        "tags": [
          "intents"
        ],
        "summary": "Leave work unfinished: a tripwire that warns whoever next edits these paths or symbols (the MCP tool defer_intent)",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  },
                  "paths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "symbols": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "expires_days": {
                    "type": "number"
                  }
                },
                "required": [
                  "repo_id",
                  "note"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/message": {
      "post": {
        "operationId": "sendAgentMessage",
        "tags": [
          "messages"
        ],
        "summary": "An agent tells the other agents in a repo something: everyone, one person, or whoever works on a piece of code",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  },
                  "about": {
                    "type": "string",
                    "description": "path::symbol: reaches whoever works on that code"
                  }
                },
                "required": [
                  "repo_id",
                  "text"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/inbox/wait": {
      "post": {
        "operationId": "waitForMessages",
        "tags": [
          "messages"
        ],
        "summary": "Held until a message arrives for the caller or wait_s (at most 25) passes; Prefer: respond-async waits longer as a job",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/Prefer"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "session": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "session",
                      "wake"
                    ]
                  },
                  "wait_s": {
                    "type": "number",
                    "maximum": 25
                  },
                  "repos": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "202": {
            "description": "Accepted as a job: poll the Location header (also status_url in the body) until the job has succeeded, failed or been cancelled.",
            "headers": {
              "Location": {
                "description": "Where to poll the job: /api/v1/jobs/{job_id}.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/api/v1/jobs/job_8c1d2f"
                },
                "required": true
              },
              "Retry-After": {
                "description": "Seconds to wait before polling the job.",
                "schema": {
                  "type": "integer"
                },
                "required": true
              },
              "Preference-Applied": {
                "description": "`respond-async` when the Prefer header was honoured.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "The API's major version: 1.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A job the server accepted: poll status_url (the same address as the Location header) until its status is succeeded, failed or cancelled.",
                  "required": [
                    "job_id",
                    "status",
                    "status_url"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "description": "The job's id.",
                      "example": "job_8c1d2f"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running"
                      ],
                      "description": "Where the job is now; a new job is queued."
                    },
                    "poll_after_s": {
                      "type": "number",
                      "description": "Seconds to wait before polling.",
                      "example": 2
                    },
                    "status_url": {
                      "type": "string",
                      "format": "uri-reference",
                      "description": "Where to poll the job: /api/v1/jobs/{job_id}, the same as the Location header.",
                      "example": "/api/v1/jobs/job_8c1d2f"
                    }
                  }
                },
                "example": {
                  "job_id": "job_8c1d2f",
                  "status": "queued",
                  "poll_after_s": 2,
                  "status_url": "/api/v1/jobs/job_8c1d2f"
                }
              }
            },
            "links": {
              "GetJob": {
                "operationId": "getJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Poll the job."
              },
              "GetJobResult": {
                "operationId": "getJobResult",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "The operation's own status and body, once the job has finished."
              },
              "CancelJob": {
                "operationId": "cancelJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Cancel the job before it finishes."
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/jobs": {
      "post": {
        "operationId": "createJob",
        "tags": [
          "jobs"
        ],
        "summary": "Start a long-running operation as a job",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted as a job: poll the Location header (also status_url in the body) until the job has succeeded, failed or been cancelled.",
            "headers": {
              "Location": {
                "description": "Where to poll the job: /api/v1/jobs/{job_id}.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/api/v1/jobs/job_8c1d2f"
                },
                "required": true
              },
              "Retry-After": {
                "description": "Seconds to wait before polling the job.",
                "schema": {
                  "type": "integer"
                },
                "required": true
              },
              "API-Version": {
                "description": "The API's major version: 1.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A job the server accepted: poll status_url (the same address as the Location header) until its status is succeeded, failed or cancelled.",
                  "required": [
                    "job_id",
                    "status",
                    "status_url"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "description": "The job's id.",
                      "example": "job_8c1d2f"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running"
                      ],
                      "description": "Where the job is now; a new job is queued."
                    },
                    "poll_after_s": {
                      "type": "number",
                      "description": "Seconds to wait before polling.",
                      "example": 2
                    },
                    "status_url": {
                      "type": "string",
                      "format": "uri-reference",
                      "description": "Where to poll the job: /api/v1/jobs/{job_id}, the same as the Location header.",
                      "example": "/api/v1/jobs/job_8c1d2f"
                    }
                  }
                },
                "example": {
                  "job_id": "job_8c1d2f",
                  "status": "queued",
                  "poll_after_s": 2,
                  "status_url": "/api/v1/jobs/job_8c1d2f"
                }
              }
            },
            "links": {
              "GetJob": {
                "operationId": "getJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Poll the job."
              },
              "GetJobResult": {
                "operationId": "getJobResult",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "The operation's own status and body, once the job has finished."
              },
              "CancelJob": {
                "operationId": "cancelJob",
                "parameters": {
                  "job_id": "$response.body#/job_id"
                },
                "description": "Cancel the job before it finishes."
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "409": {
            "$ref": "#/components/responses/IdempotencyInProgress"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      },
      "get": {
        "operationId": "listJobs",
        "tags": [
          "jobs"
        ],
        "summary": "The caller's jobs from the last 24 hours",
        "responses": {
          "200": {
            "description": "Jobs",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}": {
      "get": {
        "operationId": "getJob",
        "tags": [
          "jobs"
        ],
        "summary": "A job's status; Retry-After says when to poll again while it runs",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job id from the 202 response"
          }
        ],
        "responses": {
          "200": {
            "description": "The job",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "delete": {
        "operationId": "cancelJob",
        "tags": [
          "jobs"
        ],
        "summary": "Cancel a job that has not finished",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job id from the 202 response"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The job already finished, or a request with this Idempotency-Key is still running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyConflict"
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/result": {
      "get": {
        "operationId": "getJobResult",
        "tags": [
          "jobs"
        ],
        "summary": "The finished operation's own response: its status code and body",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The job id from the 202 response"
          }
        ],
        "responses": {
          "200": {
            "description": "The operation's response body",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The job has not finished",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 with PKCE (S256). See https://corkcli.com/auth.md",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://mcp.corkcli.com/authorize",
            "tokenUrl": "https://mcp.corkcli.com/token",
            "scopes": {
              "collide": "Act for the signed-in person in their workspaces: read briefings and activity, report edits, message teammates' agents. A viewer seat reads only."
            }
          }
        }
      },
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A dashboard sign-in token or a Cork machine credential"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid credentials",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Signed in, but not allowed here (not a member, or no seat for this repo)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadRequest": {
        "description": "The request is invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limited: wait Retry-After seconds",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "IdempotencyConflict": {
        "description": "This Idempotency-Key was already used for a different request (code idempotency_key_reused)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "IdempotencyInProgress": {
        "description": "A request with this Idempotency-Key is still running (code idempotency_key_in_progress)",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Accepted": {
        "description": "Accepted as a job: poll the Location header (also status_url in the body) until the job has succeeded, failed or been cancelled.",
        "headers": {
          "Location": {
            "$ref": "#/components/headers/Location"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "Preference-Applied": {
            "$ref": "#/components/headers/Preference-Applied"
          },
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/JobAccepted"
            }
          }
        },
        "links": {
          "GetJob": {
            "operationId": "getJob",
            "parameters": {
              "job_id": "$response.body#/job_id"
            },
            "description": "Poll the job."
          },
          "GetJobResult": {
            "operationId": "getJobResult",
            "parameters": {
              "job_id": "$response.body#/job_id"
            },
            "description": "The operation's own status and body, once the job has finished."
          },
          "CancelJob": {
            "operationId": "cancelJob",
            "parameters": {
              "job_id": "$response.body#/job_id"
            },
            "description": "Cancel the job before it finishes."
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable reason on newer endpoints",
            "enum": [
              "rate_limited",
              "idempotency_key_reused",
              "idempotency_key_in_progress",
              "not_found",
              "unauthorized",
              "invalid_request"
            ]
          },
          "retry_after_s": {
            "type": "number",
            "description": "With code rate_limited: seconds to wait"
          },
          "ok": {
            "type": "boolean",
            "const": false
          }
        }
      },
      "Object": {
        "type": "object",
        "additionalProperties": true
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "uptime_s": {
            "type": "number"
          },
          "status_page": {
            "type": "string",
            "format": "uri",
            "description": "The status page (absent on a local server)"
          },
          "status_json": {
            "type": "string",
            "format": "uri",
            "description": "The status page's JSON (absent on a local server)"
          }
        },
        "additionalProperties": true
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "WorkspaceList": {
        "type": "object",
        "properties": {
          "workspaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workspace"
            }
          }
        },
        "additionalProperties": true
      },
      "RepoList": {
        "type": "object",
        "properties": {
          "repos": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "ts": {
            "type": "number"
          },
          "anchor": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "MessageList": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          }
        },
        "additionalProperties": true
      },
      "SendMessage": {
        "type": "object",
        "required": [
          "repo",
          "text"
        ],
        "properties": {
          "repo": {
            "type": "string"
          },
          "text": {
            "type": "string",
            "maxLength": 4000
          },
          "to": {
            "type": "string",
            "description": "One person's account (email or id); omit for everyone"
          },
          "session": {
            "type": "string",
            "description": "Which of that person's agents was meant"
          },
          "anchor": {
            "type": "string",
            "description": "path::symbol, a path, or dir/: reaches whoever works on that code"
          }
        }
      },
      "Sent": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "message_id": {
            "type": "string"
          },
          "delivered_to": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "LedgerRow": {
        "type": "object",
        "properties": {
          "seq": {
            "type": "integer"
          },
          "ts": {
            "type": "number"
          },
          "kind": {
            "type": "string"
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "LedgerPage": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LedgerRow"
            }
          }
        },
        "additionalProperties": true
      },
      "JobRequest": {
        "type": "object",
        "required": [
          "operation"
        ],
        "properties": {
          "operation": {
            "type": "string",
            "enum": [
              "graph-export",
              "waste-report",
              "repo-clear",
              "inbox-wait",
              "land-turn"
            ],
            "description": "graph-export {repo_id, format?}; waste-report {workspace_id, weeks?}; repo-clear {workspace_id, repo_id, what}; inbox-wait {repo_id?, session?, role?, timeout_s? up to 3600}; land-turn {repo_id, session, timeout_s?}: waits for the repo's push turn and takes it"
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JobAccepted": {
        "type": "object",
        "description": "A job the server accepted: poll status_url (the same address as the Location header) until its status is succeeded, failed or cancelled.",
        "required": [
          "job_id",
          "status",
          "status_url"
        ],
        "properties": {
          "job_id": {
            "type": "string",
            "description": "The job's id.",
            "example": "job_8c1d2f"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running"
            ],
            "description": "Where the job is now; a new job is queued."
          },
          "poll_after_s": {
            "type": "number",
            "description": "Seconds to wait before polling.",
            "example": 2
          },
          "status_url": {
            "type": "string",
            "format": "uri-reference",
            "description": "Where to poll the job: /api/v1/jobs/{job_id}, the same as the Location header.",
            "example": "/api/v1/jobs/job_8c1d2f"
          }
        }
      },
      "Job": {
        "type": "object",
        "required": [
          "job_id",
          "status"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "operation": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed",
              "cancelled"
            ]
          },
          "created_at": {
            "type": "number"
          },
          "started_at": {
            "type": "number"
          },
          "finished_at": {
            "type": "number"
          },
          "progress": {
            "type": "object",
            "properties": {
              "elapsed_s": {
                "type": "number"
              }
            },
            "additionalProperties": true
          },
          "result_status": {
            "type": "integer",
            "description": "The operation's HTTP status"
          },
          "result": {
            "description": "The operation's JSON body, inline when small"
          },
          "result_url": {
            "type": "string",
            "description": "/api/v1/jobs/{job_id}/result"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "JobList": {
        "type": "object",
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Job"
            }
          }
        },
        "additionalProperties": true
      },
      "Plans": {
        "type": "object",
        "additionalProperties": true,
        "description": "The plans from the server's own plan table (Free included), and how an agent gets credentials: OAuth metadata, the dynamic client registration endpoint and the scope."
      },
      "StatusCheck": {
        "type": "object",
        "description": "One check that ran.",
        "required": [
          "id",
          "name",
          "status",
          "from",
          "kind"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "mcp"
            ]
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "up",
              "degraded",
              "down"
            ]
          },
          "ms": {
            "type": "integer",
            "description": "How long it took, when it is a timed request"
          },
          "note": {
            "type": "string",
            "description": "Why it did not pass"
          },
          "from": {
            "type": "string",
            "enum": [
              "server",
              "website"
            ],
            "description": "Which vantage point made it"
          },
          "kind": {
            "type": "string",
            "enum": [
              "internal",
              "external"
            ],
            "description": "Inside the server, or through a public address"
          }
        }
      },
      "StatusDay": {
        "type": "object",
        "required": [
          "date",
          "status",
          "uptime"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "status": {
            "type": "string",
            "enum": [
              "no_data",
              "operational",
              "degraded",
              "partial",
              "major"
            ],
            "description": "no_data: nothing observed (never green); partial: under 60 minutes down; major: 60 or more"
          },
          "uptime": {
            "type": [
              "number",
              "null"
            ]
          },
          "down_minutes": {
            "type": "integer"
          },
          "unrecorded_minutes": {
            "type": "integer",
            "description": "Of the down minutes: minutes with no check recorded at all"
          },
          "degraded_minutes": {
            "type": "integer"
          }
        }
      },
      "StatusUptime": {
        "type": "object",
        "required": [
          "window_days",
          "tracking_since",
          "percent"
        ],
        "properties": {
          "window_days": {
            "type": "integer",
            "examples": [
              90
            ]
          },
          "tracking_since": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this component's checks began; uptime counts from here"
          },
          "percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Minutes operational or degraded over minutes observed; null with nothing observed"
          },
          "observed_minutes": {
            "type": "integer"
          },
          "degraded_minutes": {
            "type": "integer"
          },
          "down_minutes": {
            "type": "integer"
          },
          "unrecorded_minutes": {
            "type": "integer"
          }
        }
      },
      "StatusComponent": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "checks",
          "uptime",
          "days"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "website",
              "api",
              "oauth",
              "hooks",
              "install",
              "embeddings",
              "dashboard",
              "email"
            ]
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "What is actually checked"
          },
          "status": {
            "type": "string",
            "enum": [
              "operational",
              "degraded_performance",
              "partial_outage",
              "major_outage"
            ]
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "response_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "avg_response_ms_24h": {
            "type": [
              "integer",
              "null"
            ]
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatusCheck"
            }
          },
          "uptime": {
            "$ref": "#/components/schemas/StatusUptime"
          },
          "days": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatusDay"
            },
            "description": "The last 90 UTC days, oldest first"
          }
        }
      },
      "IncidentUpdate": {
        "type": "object",
        "required": [
          "id",
          "status",
          "body",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "investigating",
              "identified",
              "monitoring",
              "resolved"
            ]
          },
          "body": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Incident": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "created_at",
          "updated_at",
          "resolved_at",
          "components",
          "incident_updates"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "investigating",
              "identified",
              "monitoring",
              "resolved"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "shortlink": {
            "type": "string",
            "format": "uri"
          },
          "components": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          },
          "incident_updates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IncidentUpdate"
            },
            "description": "Newest first"
          }
        }
      },
      "Status": {
        "type": "object",
        "description": "Cork's status, close to Statuspage's shape. Every state comes from a check that ran; uptime and the daily bars only from recorded minutes, counted from tracking_since.",
        "required": [
          "schema_version",
          "page",
          "status",
          "components",
          "incidents"
        ],
        "properties": {
          "schema_version": {
            "type": "integer",
            "const": 1
          },
          "page": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              },
              "time_zone": {
                "type": "string"
              }
            }
          },
          "status": {
            "type": "object",
            "required": [
              "indicator",
              "description"
            ],
            "properties": {
              "indicator": {
                "type": "string",
                "enum": [
                  "none",
                  "minor",
                  "major",
                  "critical"
                ],
                "description": "critical: the website or the API and MCP server fully down, or half the components down; major: any component down; minor: any degraded"
              },
              "description": {
                "type": "string",
                "examples": [
                  "All systems operational"
                ]
              }
            }
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatusComponent"
            }
          },
          "incidents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Incident"
            },
            "description": "Open incidents first, then those resolved in the last 90 days"
          },
          "server": {
            "type": "object",
            "properties": {
              "reachable": {
                "type": "boolean",
                "description": "status.json only: whether the website read the server's record just now"
              },
              "commit": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "hooks_version": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "last_check_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "tracking_since": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "fetched_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "website": {
            "type": "object",
            "properties": {
              "commit": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "checked_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "checked_from": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "server",
                "website"
              ]
            }
          },
          "rules": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Makes a retry safe: the same key and request within 24 hours returns the first response (with Idempotent-Replayed: true). Scoped to the caller. A different request with the same key gets 422.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      },
      "Prefer": {
        "name": "Prefer",
        "in": "header",
        "required": false,
        "description": "`respond-async` runs the operation as a job and answers 202 with a Location to poll (RFC 7240).",
        "schema": {
          "type": "string",
          "enum": [
            "respond-async"
          ]
        }
      }
    },
    "headers": {
      "RateLimit": {
        "description": "Remaining quota and seconds until it is full again, e.g. `\"rest\";r=598;t=1` (draft-ietf-httpapi-ratelimit-headers).",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit-Policy": {
        "description": "The quota policy, e.g. `\"rest\";q=600;w=60`.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit-Limit": {
        "description": "Requests allowed in a burst.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left right now.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the quota is full again.",
        "schema": {
          "type": "integer"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying (a 429, a 409, or a job still running).",
        "schema": {
          "type": "integer"
        }
      },
      "API-Version": {
        "description": "The API's major version: 1.",
        "schema": {
          "type": "string",
          "const": "1"
        }
      },
      "Deprecation": {
        "description": "On unversioned /api/... paths only: when the path was deprecated (RFC 9745).",
        "schema": {
          "type": "string"
        }
      },
      "Link": {
        "description": "On unversioned paths: the successor-version v1 path and the deprecation policy.",
        "schema": {
          "type": "string"
        }
      },
      "Idempotent-Replayed": {
        "description": "`true` when this is a stored response replayed for a repeated Idempotency-Key.",
        "schema": {
          "type": "string",
          "enum": [
            "true"
          ]
        }
      },
      "Location": {
        "description": "Where to poll the job: /api/v1/jobs/{job_id}.",
        "schema": {
          "type": "string"
        }
      },
      "Preference-Applied": {
        "description": "`respond-async` when the Prefer header was honoured.",
        "schema": {
          "type": "string"
        }
      }
    }
  }
}
