openapi.yaml

# OpenAPI 3.1 description of the af-hub REST API.
#
# Derived from the hub source tree and from apikit (github.com/txsvc/apikit,
# resolved through the `replace` directive in go.mod), cross-checked against
# docs/api.md and docs/permissions.md. Endpoints served by apikit rather than
# by hub code are marked `x-provider: apikit`. Where the prose docs disagree
# with the handlers, the handlers win; the divergences are recorded in
# docs/errata/openapi_description.md.
openapi: 3.1.0

info:
  title: agent-fox hub REST API
  version: "0.19.0"
  summary: Headless harness for spec-driven, multi-agent software development.
  description: |
    The `hub` binary is the API server for agent-fox. It owns user identity,
    OAuth, workspaces, git hosting, the merge queue, carry-patch workflows,
    secrets, variables, agent sessions, and audit storage.

    ## Base paths

    | Prefix | Contents |
    |--------|----------|
    | `/api/v1` | Everything under the API mount point: workspaces, patches, rebuilds, merges, secrets, variables, sessions, audit, and the apikit identity and administration endpoints |
    | `/git` | Built-in git smart HTTP server (`/git/<org>/<slug>.git`) |
    | *(root)* | `/healthz`, `/readyz`, `/version`, and `/metrics` |

    The `/api/v1` prefix comes from `server.mount_point` in `config.toml` and
    defaults to `/api/v1`. Everything apikit mounts -- `/user`, `/users`,
    `/orgs`, `/auth` -- goes on that same group, so those paths are
    `/api/v1/user`, `/api/v1/users`, and so on. `docs/api.md` and
    `docs/permissions.md` both write them without the prefix; see
    `docs/errata/openapi_description.md`.

    ## Authentication

    Every `/api/v1` endpoint requires a bearer credential, except the two
    OAuth routes (`GET /api/v1/auth/providers` and
    `POST /api/v1/auth/callback`), which are registered before the auth
    middleware is attached to the group. Three credential types exist:

    - **Admin token** (`af_admin_<64-hex>`) -- implicit full access, bypasses
      permission and ownership checks. Cannot create workspaces (no user
      identity to own them).
    - **API key** (`af_<key_id>_<secret>`) -- implicit full access to the
      owning user's resources. Created only through the OAuth login flow.
    - **Personal access token / PAT** (`af_pat_<token_id>_<secret>`) --
      explicit scope-based access, restricted to the scopes granted at
      creation. Never treated as admin, even for admin-role users.

    Scope checks constrain PATs only. Each operation records the scopes it
    accepts in the non-standard `x-required-scopes` field; an empty list
    means no PAT scope check is performed.

    The git smart HTTP endpoints use HTTP Basic authentication instead: the
    username is ignored and the password must be any valid hub credential.

    ## Anti-enumeration policy

    Workspace CRUD endpoints (list, get, update, archive, reactivate, delete)
    return `404` -- not `403` -- when a PAT lacks the required scope or the
    workspace is not owned by the caller, so that workspace slugs cannot be
    enumerated. The git server likewise answers `404` for non-owner access.
    Workspace *creation* returns `403`, because there is no existing resource
    to enumerate. Other endpoint families return `403` for a missing scope.

    ## Ownership enforcement

    Ownership is enforced on every workspace-scoped endpoint: sync, reclone,
    patches, merges, rebuilds, rerere, patch-status, sessions and audit
    reads look the workspace up by slug *and* owner and answer `404` for a
    workspace the caller does not own (admin tokens bypass). The unified
    audit query and SSE stream are restricted to the caller's workspaces.

    ## Workspace lock

    Operations that modify a workspace clone are serialised per workspace.
    Handlers that cannot take the lock immediately answer `409` with
    `error_type: workspace_busy`.

    A carry-patch rebuild applies patches in its own detached worktree and
    holds the lock only for its fetch phase (upstream fetch and base
    resolution) and its final phase (integration-ref update, patch
    bookkeeping, optional push to `origin`). Sync, rollback, rerere forget and
    batch rebase are rejected only while a rebuild is in one of those two
    phases. Archive and reclone delete the directory the worktree lives in, so
    they answer `409 workspace_busy` for the whole rebuild.

    ## Error envelope

    All errors use the apikit envelope: `{"error": {"code": N, "message":
    "..."}}`. Some handlers add a machine-readable `error_type` field.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  contact:
    name: agent-fox hub
    url: https://github.com/agent-fox-dev/hub

servers:
  - url: http://localhost:8080
    description: Local development server (default `server.port` = 8080)
  - url: "{external_url}"
    description: Deployment configured through `server.external_url` in config.toml
    variables:
      external_url:
        default: http://localhost:8080

externalDocs:
  description: Hand-written API reference
  url: https://github.com/agent-fox-dev/hub/blob/main/docs/api.md

tags:
  - name: Health
    description: Liveness and readiness probes. Unauthenticated.
  - name: Metrics
    description: Prometheus exposition endpoint. Unauthenticated.
  - name: Workspaces
    description: Workspace lifecycle -- create, list, update, archive, sync, reclone, delete.
  - name: Patches
    description: Ordered patch-branch list for carry-patch workspaces.
  - name: Rerere
    description: Recorded git rerere conflict resolutions.
  - name: Rebuilds
    description: Integration-branch rebuild jobs for carry-patch workspaces.
  - name: Merges
    description: Rebase-then-fast-forward merge queue and batch rebase.
  - name: Secrets
    description: Write-only secret storage scoped to a user, org, or workspace.
  - name: Variables
    description: Readable variable storage scoped to a user, org, or workspace.
  - name: Sessions
    description: Agent session lifecycle, token usage, and cost aggregation.
  - name: Audit Ingestion
    description: Per-run telemetry ingestion and query (DuckDB backed).
  - name: Audit Query
    description: Unified audit query, transcripts, and the SSE event stream.
  - name: Git
    description: Built-in git smart HTTP server.
  - name: Identity
    description: >-
      OAuth login, the caller's own profile, API keys, and personal access
      tokens. Provided by apikit and mounted under the API prefix.
  - name: Administration
    description: >-
      Cross-tenant user and organization administration. Provided by apikit;
      requires an admin token or an admin-role API key.

security:
  - bearerAuth: []

paths:

  # ---------------------------------------------------------------------------
  # Health and metrics
  # ---------------------------------------------------------------------------

  /healthz:
    get:
      tags: [Health]
      operationId: getHealthz
      summary: Liveness probe
      description: Reports that the process is up. Mounted outside the API auth group.
      security: []
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The server is alive.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    const: ok
              example: { status: ok }

  /readyz:
    get:
      tags: [Health]
      operationId: getReadyz
      summary: Readiness probe
      description: |
        Runs the registered health checker, which pings the primary SQLite
        database. Mounted outside the API auth group.
      security: []
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The server is ready to serve traffic.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    const: ready
              example: { status: ready }
        "503":
          description: A dependency (the database) is unreachable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /metrics:
    get:
      tags: [Metrics]
      operationId: getMetrics
      summary: Prometheus metrics
      description: |
        Scrapes all `afhub_*` metrics from the custom Prometheus registry in
        the text exposition format. Mounted outside the API auth middleware,
        so no `Authorization` header is required.

        Exposed series: `afhub_http_requests_total`,
        `afhub_http_request_duration_seconds`, `afhub_agent_sessions_active`,
        `afhub_agent_tokens_total`, `afhub_audit_events_total`,
        `afhub_audit_table_rows`, `afhub_retention_errors_total`,
        `afhub_retention_last_run_timestamp_seconds`, `afhub_sse_connections`,
        and `afhub_jobqueue_depth`.

        The `path` label carries the Echo route template (for example
        `/api/v1/sessions/:id`) rather than the resolved URI, to bound
        cardinality.
      security: []
      x-required-scopes: []
      responses:
        "200":
          description: Metrics in Prometheus text exposition format.
          content:
            text/plain:
              schema:
                type: string

  # ---------------------------------------------------------------------------
  # Workspaces
  # ---------------------------------------------------------------------------

  /api/v1/workspaces:
    post:
      tags: [Workspaces]
      operationId: createWorkspace
      summary: Create a workspace
      description: |
        Creates a workspace and enqueues an asynchronous clone job. The
        response is returned immediately with `clone_status` set to
        `pending`; poll `GET /api/v1/workspaces/{slug}` to observe the
        transition to `cloning` and then `ready` or `failed`.

        When `org_id` is omitted or empty the server assigns the caller's
        personal organization; if the caller has none, the request fails with
        `400`.

        Git credentials supplied in the body are validated with `ls-remote`,
        stored as workspace secrets, and zeroed out of the request struct
        immediately after binding so they never reach logs.

        Admin tokens are rejected with `403`: a workspace requires a real
        user as owner.
      x-required-scopes: ["workspaces:create"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceRequest"
            examples:
              standard:
                summary: Standard workspace
                value:
                  slug: my-project
                  git_url: https://github.com/user/repo.git
                  branch: main
                  display_name: My Project
                  description: A description of the workspace
              carryPatch:
                summary: Carry-patch workspace with a private upstream
                value:
                  slug: vendor-fork
                  git_url: https://github.com/acme/vendor-fork.git
                  workspace_mode: carry_patch
                  upstream_url: https://github.com/upstream/repo.git
                  integration_branch: deploy
                  git_pat: ghp_xxxxxxxxxxxx
      responses:
        "201":
          description: Workspace created; the clone job is queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "400":
          description: |
            Missing `slug` or `git_url`; `display_name` over 128 characters;
            `description` over 1024 characters; invalid `sync_mode` or
            `workspace_mode`; `upstream_url` missing for a carry-patch
            workspace or supplied for a standard one; git credentials that are
            empty, mutually exclusive, incompletely paired, used with a
            non-HTTPS `git_url`, or that fail the `ls-remote` check; or the
            caller has no personal organization while `org_id` was omitted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: >-
            An admin token attempted to create a workspace, or the PAT lacks
            the `workspaces:create` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: A workspace with this slug already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Workspaces]
      operationId: listWorkspaces
      summary: List workspaces
      description: |
        Non-admin callers see only workspaces they own. Admin tokens see every
        workspace on the server.
      x-required-scopes: ["workspaces:read", "workspaces:create", "workspaces:write"]
      parameters:
        - name: include_archived
          in: query
          required: false
          description: >-
            Include archived workspaces in the listing. Only the exact string
            `true` enables this.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: The accessible workspaces.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: The PAT lacks read access (anti-enumeration).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Workspaces]
      operationId: getWorkspace
      summary: Get a workspace
      x-required-scopes: ["workspaces:read", "workspaces:create", "workspaces:write"]
      responses:
        "200":
          description: The workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrForbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
    patch:
      tags: [Workspaces]
      operationId: updateWorkspace
      summary: Update mutable workspace properties
      description: |
        Partial update: only the fields present in the body are modified.
        At least one field must be supplied.

        `slug`, `git_url`, `branch`, `owner_id`, `workspace_mode`,
        `upstream_url`, and `integration_branch` are immutable -- including any
        of them in the body is rejected with `400`. `updated_at` is advanced on
        every successful update.
      x-required-scopes: ["workspaces:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceRequest"
      responses:
        "200":
          description: The updated workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "400":
          description: >-
            Empty body; workspace is archived (reactivate first);
            `display_name` over 128 characters; `description` over 1024
            characters; an immutable field was included; or `sync_mode` is
            invalid or null.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The workspace owner is not a member of the organization in `org_id`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrForbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Workspaces]
      operationId: deleteWorkspace
      summary: Permanently delete an archived workspace
      description: |
        Only archived workspaces can be deleted. `workspaces:delete` does not
        imply `workspaces:read`.
      x-required-scopes: ["workspaces:delete"]
      responses:
        "204":
          description: Workspace deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrForbidden"
        "409":
          description: The workspace is not archived.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/archive:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Workspaces]
      operationId: archiveWorkspace
      summary: Archive a workspace
      description: |
        Archived workspaces are read-only; all state is preserved and the
        workspace can be reactivated later. Any active agent sessions for the
        workspace are force-closed and an audit event is emitted.
      x-required-scopes: ["workspaces:write"]
      responses:
        "200":
          description: The archived workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "400":
          description: The workspace is already archived.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrForbidden"
        "409":
          description: >-
            A clone is in progress (archiving is rejected until it settles), or
            another operation holds the workspace lock (`error_type:
            workspace_busy`). A running carry-patch rebuild makes archive answer
            `workspace_busy` for the whole rebuild.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/reactivate:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Workspaces]
      operationId: reactivateWorkspace
      summary: Reactivate an archived workspace
      description: |
        Restores `status` to `active`, resets `clone_status` to `pending`, and
        enqueues a reclone job.
      x-required-scopes: ["workspaces:write"]
      responses:
        "200":
          description: The reactivated workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrForbidden"
        "409":
          description: The workspace is not archived.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/sync:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Workspaces]
      operationId: syncWorkspace
      summary: Sync a workspace with its upstream
      description: |
        Fetches from the remote and fast-forwards the local integration branch
        when possible. Ownership is **not** enforced: any authenticated caller
        holding the scope may sync any workspace.

        Preconditions: `status` is `active`, `clone_status` is `ready`,
        `sync_mode` is not `disabled`, and `sync_status` is not `syncing`.

        `sync_status` follows a strict state machine
        (`idle -> syncing -> idle|error`, `error -> syncing -> idle`); a
        deferred cleanup guarantees it never remains stuck at `syncing`.

        ### Response shape

        The response is always the updated workspace object. For a
        `carry_patch` workspace the request is delegated to the carry-patch
        sync extension -- which fetches the `upstream` remote, detects patches
        merged upstream, flags upstream force-pushes, and may enqueue a
        rebuild -- and its four fields are merged into the workspace JSON as
        additional top-level keys, per 16-REQ-5.1. The workspace row is
        re-read after the extension runs, so `upstream_head_sha` and
        `last_sync_at` reflect its writes.

        A `standard` workspace takes the standard sync path and carries none
        of the carry-patch fields (16-REQ-5.E4).

        Merge detection for carry-patch workspaces is governed by the
        `SQUASH_MERGE_DETECTION` workspace variable (`ancestry_only`,
        `content_based`, or `both`, the default). A rebuild is enqueued when
        the upstream ref advanced unless `AUTO_REBUILD_AFTER_SYNC` is
        `"false"`; a duplicate enqueue is ignored silently and leaves
        `rebuild_triggered` false.
      x-required-scopes: ["workspaces:sync", "workspaces:write"]
      x-scope-note: >-
        The standard sync path requires `workspaces:sync` exclusively. The
        carry-patch path also accepts `workspaces:write`.
      parameters:
        - name: reset_to_upstream
          in: query
          required: false
          description: >-
            Force-reset the local integration branch to the upstream HEAD,
            ignoring ancestry. Used to recover from a diverged (force-pushed)
            upstream. Standard workspaces only.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: |
            Sync completed. The body is the updated workspace; a carry-patch
            workspace additionally carries `patches_merged`,
            `rebuild_triggered`, `force_push_detected`, and -- when a rebuild
            was enqueued -- `rebuild_job_id`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Workspace"
                  - $ref: "#/components/schemas/CarryPatchSyncResponse"
              examples:
                standard:
                  summary: Standard workspace, fast-forwarded
                  value:
                    slug: my-project
                    status: active
                    clone_status: ready
                    sync_status: idle
                    workspace_mode: standard
                    head_sha: fedcba9876543210fedcba9876543210fedcba98
                    upstream_head_sha: fedcba9876543210fedcba9876543210fedcba98
                    last_sync_at: "2026-09-01T12:00:00Z"
                carryPatch:
                  summary: Carry-patch workspace, rebuild enqueued
                  value:
                    slug: vendor-fork
                    status: active
                    clone_status: ready
                    sync_status: idle
                    workspace_mode: carry_patch
                    upstream_url: https://github.com/upstream/repo.git
                    integration_branch: deploy
                    upstream_head_sha: abc123def456abc123def456abc123def456abcd
                    last_sync_at: "2026-09-01T12:00:00Z"
                    patches_merged: ["feature/already-merged"]
                    rebuild_triggered: true
                    rebuild_job_id: d3b07384-d113-4ec5-8a4e-a12345678901
                    force_push_detected: false
        "400":
          description: The workspace is not active, the clone is not ready, or sync is disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The PAT lacks the `workspaces:sync` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "409":
          description: >-
            A sync is already in progress, or the upstream history has diverged
            (force-push detected) on a standard workspace, or another operation
            holds the workspace lock (`error_type: workspace_busy`). A rebuild
            holds the lock only during its fetch phase and final phase, not
            while it applies patches.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          description: >-
            Upstream fetch failed (network, authentication, or repository
            error), or credential resolution failed. In origin mode, also
            returned when the origin fetch fails (`error_type:
            origin_fetch_failed`) or origin credentials cannot be resolved
            (`failed to resolve origin credentials`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: The request context was cancelled mid-sync.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/workspaces/{slug}/reclone:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Workspaces]
      operationId: recloneWorkspace
      summary: Nuclear recovery -- delete and re-clone the local repository
      description: |
        Runs the archive flow (attempting to push local commits upstream first;
        a failed push is logged and does not abort), deletes
        `<WORKSPACE_ROOT>/<slug>/`, resets `clone_status` to `pending`, clears
        `sync_error` and `upstream_head_sha`, and enqueues a clone job. The
        workspace `status` stays `active` throughout.

        Ownership is not enforced.
      x-required-scopes: ["workspaces:sync"]
      responses:
        "200":
          description: Reclone accepted; the clone job is queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The PAT lacks the `workspaces:sync` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "409":
          description: >-
            A clone is already in progress (`clone_status` is `pending` or
            `cloning`), or another operation holds the workspace lock, or a
            carry-patch rebuild is running (`error_type: workspace_busy`;
            reclone is rejected for the whole rebuild).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Failed to delete the workspace directory, or the database update failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ---------------------------------------------------------------------------
  # Patches
  # ---------------------------------------------------------------------------

  /api/v1/workspaces/{slug}/patches:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Patches]
      operationId: addPatches
      summary: Add one or more patches
      description: |
        Accepts either a single patch object or a JSON array of them. A batch
        is validated and inserted inside one transaction: if any entry fails,
        nothing is inserted.

        When `position` is omitted the patch is appended at `max(position) + 1`.
        When it is supplied, existing patches at that position and beyond are
        shifted down by one. Positions greater than `max + 1` are clamped to an
        append.

        Unless `skip_branch_check` is `true`, the server resolves the branch
        in this order: (1) `local` — `refs/heads/<name>` exists in the trunk;
        (2) `origin_tracking` — `refs/remotes/origin/<name>` exists and a
        local branch is created at that commit; (3) `origin_fetch` — only
        when `PATCH_BRANCH_SOURCE` is `origin`, the branch is fetched from
        the fork and the local branch is created. Tags, bare SHAs and
        remote-qualified names are not accepted. `PATCH_BRANCH_SOURCE` is read
        once per request, so every element of a batch resolves in the same
        mode.

        A batch validates the syntax of every element first (name,
        integration branch, position) and starts resolving branches only
        after all elements pass.

        Ownership is not enforced.
      x-required-scopes: ["patches:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AddPatchRequest"
                - type: array
                  items:
                    $ref: "#/components/schemas/AddPatchRequest"
            examples:
              single:
                summary: Single patch
                value:
                  branch_name: feature/auth-headers
                  position: 2
                  upstream_pr_url: https://github.com/upstream/repo/pull/42
                  description: Add authentication headers to API
              batch:
                summary: Batch insert
                value:
                  - { branch_name: feature/a, position: 1 }
                  - { branch_name: feature/b }
                  - { branch_name: feature/c, upstream_pr_url: "https://github.com/upstream/repo/pull/99" }
      responses:
        "200":
          description: >-
            `if_not_exists` was true and the branch is already registered; the
            existing patch is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Patch"
        "201":
          description: The created patch, or the array of created patches for a batch request.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Patch"
                  - type: array
                    items:
                      $ref: "#/components/schemas/Patch"
        "400":
          description: >-
            `branch_name` is absent or empty; `branch_name` equals the
            workspace `integration_branch`; the workspace is missing, inactive,
            or in `standard` mode; `position` is below 1; or the branch does
            not exist in the repository or on origin and `skip_branch_check`
            is false. In a batch the message is prefixed `patch[i]: `.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "409":
          description: >-
            The branch is already registered for this workspace (and
            `if_not_exists` is false), or the batch contains a duplicate
            `branch_name`, or another operation holds the workspace lock
            (`error_type: workspace_busy`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          description: >-
            Origin fetch failed (`error_type: origin_fetch_failed`). Returned
            when `PATCH_BRANCH_SOURCE` is `origin` and the fetch from the fork
            fails due to a network or authentication error, or when origin
            credentials cannot be resolved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      tags: [Patches]
      operationId: listPatches
      summary: List patches
      description: |
        Returns every non-deleted patch ordered by ascending position.
        Soft-deleted patches (status `deleted`) are excluded. Standard
        (non-carry-patch) workspaces return an empty array rather than an
        error. Ownership is not enforced.
      x-required-scopes: ["patches:read", "patches:write"]
      responses:
        "200":
          description: The patch list in position order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Patch"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/patches/{id}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/PatchId"
    get:
      tags: [Patches]
      operationId: getPatch
      summary: Get a single patch
      description: |
        Returns the patch record. When `refs/hub/replaced/<branch>` resolves
        to a commit, the response also carries `replaced_sha` (the full
        40-character SHA). The field is omitted when the ref does not exist,
        the trunk is not on disk, no recovery hook is registered, or the
        lookup fails. A soft-deleted patch is returned with its `deleted`
        status.
      x-required-scopes: ["patches:read", "patches:write"]
      responses:
        "200":
          description: The patch.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Patch"
                  - type: object
                    properties:
                      replaced_sha:
                        type: string
                        description: >
                          Full 40-character SHA of the backup ref
                          `refs/hub/replaced/<branch>`. Omitted when the ref
                          does not exist.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/PatchNotFound"
    patch:
      tags: [Patches]
      operationId: updatePatch
      summary: Update a patch
      description: |
        Only the supplied fields change. `branch_name` is immutable and is
        silently ignored if present. Changing `position` reshuffles the other
        patches so positions stay a contiguous 1-based sequence.
      x-required-scopes: ["patches:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePatchRequest"
      responses:
        "200":
          description: The updated patch.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Patch"
        "400":
          description: >-
            `status` is not one of the valid values, or `position` is below 1 or
            above the total patch count.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/PatchNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Patches]
      operationId: removePatch
      summary: Remove a patch
      description: |
        Deletes the patch row and compacts the remaining positions to a
        contiguous 1-based sequence. Both steps run in a single transaction.
      x-required-scopes: ["patches:write"]
      responses:
        "204":
          description: Patch removed and positions compacted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/PatchNotFound"
        "500":
          description: The delete-and-compact transaction failed; no partial state was persisted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/workspaces/{slug}/patches/{id}/restore:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/PatchId"
    post:
      tags: [Patches]
      operationId: restorePatch
      summary: Restore a soft-deleted patch
      description: |
        Moves the patch from `deleted` back to `active`, clears `deleted_at`,
        and appends it at `max(position) + 1`.
      x-required-scopes: ["patches:write"]
      responses:
        "200":
          description: The restored patch.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Patch"
        "400":
          description: >-
            The workspace is missing, inactive, or not in `carry_patch` mode, or
            the patch is not in `deleted` status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/PatchNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/patches/{id}/reset-to-origin:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/PatchId"
    post:
      tags: [Patches]
      operationId: resetPatchToOrigin
      summary: Reset a patch branch to the fork's current tip
      description: |
        Fetches the branch from the fork, compares the tips, and moves the
        local branch to the fork's tip regardless of `PATCH_DIVERGENCE_POLICY`.
        If the move discards commits, the old tip is saved under
        `refs/hub/replaced/<branch>`. A fast-forward does not touch an existing
        backup.
      x-required-scopes: ["patches:write"]
      responses:
        "200":
          description: |
            The patch object as GET renders it, plus `rebuild_triggered` and
            optionally `rebuild_job_id`.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Patch"
                  - type: object
                    properties:
                      replaced_sha:
                        type: string
                        description: >
                          Full 40-character SHA of the backup ref. Present
                          only when a backup exists after the reset.
                      rebuild_triggered:
                        type: boolean
                        description: Whether a rebuild job was enqueued.
                      rebuild_job_id:
                        type: string
                        description: >
                          ID of the enqueued rebuild job. Omitted when no
                          rebuild was enqueued.
        "400":
          description: >-
            Workspace is not active; workspace is not in `carry_patch` mode;
            patch branch is the integration branch.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: >-
            Workspace not found or not owned by the caller; patch not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: >-
            Workspace clone is not ready; patch status cannot be reset;
            branch does not exist on origin (`error_type: missing_on_origin`);
            patch branch changed during reset (`error_type: ref_changed`);
            another operation holds the workspace lock
            (`error_type: workspace_busy`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: >-
            Patch reset is not configured; failed to update patch branch.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: >-
            Origin fetch failed (`error_type: origin_fetch_failed`); failed
            to resolve origin credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/workspaces/{slug}/patches/reorder:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Patches]
      operationId: reorderPatches
      summary: Reorder the whole patch list
      description: |
        `patch_ids` must list exactly the workspace's patch IDs -- no missing,
        extra, or duplicated entries. New positions are assigned from the array
        index (first element becomes position 1). The whole reorder runs in one
        transaction.
      x-required-scopes: ["patches:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReorderPatchesRequest"
      responses:
        "200":
          description: All patches in their new order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Patch"
        "400":
          description: >-
            `patch_ids` is empty while patches exist, omits an existing patch,
            contains duplicates, references a patch from another workspace, or
            the bulk position update failed. Every reorder error surfaces as
            `400`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"

  # ---------------------------------------------------------------------------
  # Rerere
  # ---------------------------------------------------------------------------

  /api/v1/workspaces/{slug}/rerere:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Rerere]
      operationId: listRerereResolutions
      summary: List recorded rerere resolutions
      description: |
        Reads `.git/rr-cache/` in the workspace clone. A missing or empty
        cache yields `{"resolutions": []}`; malformed cache subdirectories
        (missing preimage or postimage) are skipped silently.

        This handler requires the literal `workspaces:read` scope --
        `workspaces:create` and `workspaces:write` do **not** satisfy it.
        Ownership is not enforced.
      x-required-scopes: ["workspaces:read"]
      responses:
        "200":
          description: The recorded resolutions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RerereListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/rerere/{pathspec}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - name: pathspec
        in: path
        required: true
        description: >-
          File path whose recorded resolution should be forgotten. This is an
          Echo wildcard parameter, so it may contain slashes (for example
          `src/config.go`); do not percent-encode them.
        schema:
          type: string
        example: src/config.go
    delete:
      tags: [Rerere]
      operationId: forgetRerereResolution
      summary: Forget a recorded rerere resolution
      description: |
        Runs `git rerere forget <pathspec>` in the workspace clone. Requires
        the literal `workspaces:write` scope. Ownership is not enforced.
      x-required-scopes: ["workspaces:write"]
      responses:
        "204":
          description: The resolution was forgotten.
        "400":
          description: The pathspec is empty.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          description: The workspace does not exist, or no resolution is recorded for the pathspec.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: >-
            Another operation holds the workspace lock (`error_type:
            workspace_busy`). A rebuild holds it only during its fetch phase
            and final phase, not while it applies patches.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Rebuilds
  # ---------------------------------------------------------------------------

  /api/v1/workspaces/{slug}/rebuild:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Rebuilds]
      operationId: submitRebuild
      summary: Submit a rebuild job
      description: |
        Enqueues a job that reconstructs the integration branch from the
        upstream HEAD plus every applicable patch, in position order.

        Preconditions: the workspace is in `carry_patch` mode, `status` is
        `active`, `clone_status` is `ready`, at least one patch is `active` or
        `conflict`, and no rebuild job for this workspace is queued or running.

        With no body, `strategy` falls back to the `REBUILD_STRATEGY` workspace
        variable (`rebase` if unset) and `fail_mode` to `REBUILD_FAIL_MODE`.
        If neither the body nor a variable supplies `fail_mode`, it is left
        empty at enqueue time and the executor applies `fail_fast` at runtime.

        The executor: fetches upstream, creates a detached git worktree at the
        upstream HEAD (the workspace's trunk checkout is never changed),
        enables rerere, resolves each patch branch to a tip SHA
        (`patch_results[].source_sha`), then for each patch in order skips `merged_upstream`,
        `disabled`, `deleted`, and missing-branch patches and otherwise applies
        it (`rebase` cherry-picks each unique commit; `merge` uses
        `git merge --no-ff`). Conflicts are replayed through rerere; anything
        still unresolved either aborts the rebuild (`fail_fast`) or marks the
        patch `conflict` and continues (`continue`). Finally the integration
        ref is force-updated, `merged_upstream` patches are soft-deleted, and
        the remaining positions are compacted. If a patch tip or the upstream
        base moved during the run, one follow-up rebuild is enqueued
        (`submitted_by: system:stale-snapshot`).

        A rebuild is also enqueued automatically when a push lands on a
        registered patch branch, unless `AUTO_REBUILD_AFTER_PUSH` is `"false"`.

        Ownership is not enforced.
      x-required-scopes: ["rebuilds:write"]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitRebuildRequest"
      responses:
        "202":
          description: The rebuild job was enqueued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RebuildJobEnqueued"
        "400":
          description: >-
            The workspace is not in `carry_patch` mode
            (`error_type: workspace_mode_mismatch`), is not active, the clone is
            not ready, no patch is `active` or `conflict`
            (`error_type: no_active_patches`), or `strategy` / `fail_mode` is
            invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "409":
          description: "A rebuild job is already queued or running (`error_type: concurrent_rebuild`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  code: 409
                  message: a rebuild job is already queued or running for this workspace
                  error_type: concurrent_rebuild
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/rebuilds:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Rebuilds]
      operationId: listRebuilds
      summary: List rebuild jobs
      description: |
        Ordered by creation time, newest first. Workspace existence is not
        validated -- an unknown slug returns `200` with an empty `jobs` array.
        Ownership is not enforced.
      x-required-scopes: ["rebuilds:read"]
      responses:
        "200":
          description: The rebuild jobs for this workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RebuildListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/rebuilds/{id}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/JobId"
    get:
      tags: [Rebuilds]
      operationId: getRebuild
      summary: Get a rebuild job
      description: |
        For running jobs `patch_results` exposes intermediate progress as each
        patch completes, so clients can poll this endpoint instead of waiting
        for the whole rebuild.
      x-required-scopes: ["rebuilds:read"]
      responses:
        "200":
          description: The rebuild job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RebuildJob"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
    delete:
      tags: [Rebuilds]
      operationId: cancelRebuild
      summary: Cancel a queued rebuild job
      x-required-scopes: ["rebuilds:write"]
      responses:
        "200":
          description: The job was cancelled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelledAck"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
        "409":
          description: The job is not in `queued` status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/rebuilds/{id}/requeue:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/JobId"
    post:
      tags: [Rebuilds]
      operationId: requeueRebuild
      summary: Requeue a dead-lettered rebuild job
      x-required-scopes: ["rebuilds:write"]
      responses:
        "200":
          description: The requeued rebuild job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RebuildJob"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
        "409":
          description: >-
            The job is not in `dead_letter` status, or an active rebuild job
            already exists for this workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/rebuilds/{id}/rollback:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/JobId"
    post:
      tags: [Rebuilds]
      operationId: rollbackRebuild
      summary: Roll the integration branch back to a pre-rebuild state
      description: >-
        Resets the integration branch to the `previous_integration_head_sha`
        recorded in the rebuild result. Backs `afc rebuild rollback`.
        Ownership is not enforced.
      x-required-scopes: ["rebuilds:write"]
      responses:
        "200":
          description: The integration branch was reset.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollbackResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
        "409":
          description: >-
            No previous integration head is available to roll back to (first
            rebuild, or the job carries no result), or another operation holds
            the workspace lock (`error_type: workspace_busy`). A rebuild holds
            it only during its fetch phase and final phase, not while it
            applies patches.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Failed to initialise the git runner, or failed to reset the branch.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/workspaces/{slug}/rebuild-preview:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Rebuilds]
      operationId: previewRebuild
      summary: Predict rebuild conflicts without mutating anything
      description: |
        Runs `git merge-tree --write-tree` for each patch in position order.
        No refs, branches, or patch statuses are modified.

        Patches with status `disabled` or `merged_upstream` are skipped. The
        preview is cumulative: each patch predicted to succeed contributes to
        the base used for the next one, and a predicted conflict does not stop
        the remaining patches from being tested against the last successful
        base.

        Ownership is not enforced.
      x-required-scopes: ["rebuilds:read"]
      responses:
        "200":
          description: Per-patch conflict predictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RebuildPreviewResponse"
        "400":
          description: The workspace is not in `carry_patch` mode.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "500":
          description: >-
            Failed to resolve the upstream HEAD, list patches, or initialise the
            git runner.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/workspaces/{slug}/patch-status:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Rebuilds]
      operationId: getPatchStatus
      summary: Carry-patch health dashboard
      description: |
        Aggregates workspace metadata, the most recent rebuild result,
        per-patch status, and summary counts including the total number of
        recorded rerere resolutions.

        Invariant: `summary.total_patches == len(patches)` and
        `summary.active + summary.merged_upstream + summary.conflict +
        summary.disabled == summary.total_patches`.

        If the rr-cache is unreadable, `summary.total_rerere_resolutions` is
        reported as `0` rather than failing the request. Soft-deleted patches
        are excluded.

        Requires the literal `workspaces:read` scope. Ownership is not enforced.
      x-required-scopes: ["workspaces:read"]
      responses:
        "200":
          description: The carry-patch status dashboard.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PatchStatusResponse"
        "400":
          description: The workspace is not in `carry_patch` mode.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Merges
  # ---------------------------------------------------------------------------

  /api/v1/workspaces/{slug}/merges:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Merges]
      operationId: submitMerge
      summary: Submit a merge job
      description: |
        Queues a rebase-then-fast-forward integration of `source_ref` into
        `target_branch`. Jobs are serialised per target through the durable
        job queue's group key, so at most one merge per target runs at a time.

        If the `CHECK_COMMAND` workspace variable is set, it runs via `sh -c`
        after the rebase; a non-zero exit rolls the rebase back.

        Ownership is not enforced.
      x-required-scopes: ["merges:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitMergeRequest"
      responses:
        "202":
          description: The merge job was queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeJob"
        "400":
          description: >-
            `target_branch` or `source_ref` is missing, the JSON is malformed,
            the workspace is not active, the clone is not ready, or the source
            or target branch does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "409":
          description: >-
            A merge job for this source and target is already queued or running
            (`error_type: duplicate_merge`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Merges]
      operationId: listMerges
      summary: List merge jobs
      description: |
        Workspace existence is not validated -- an unknown slug returns `200`
        with an empty array. Ownership is not enforced.
      x-required-scopes: ["merges:read"]
      responses:
        "200":
          description: The merge jobs scoped to this workspace.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MergeJob"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/merges/{id}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/JobId"
    get:
      tags: [Merges]
      operationId: getMerge
      summary: Get a merge job
      x-required-scopes: ["merges:read"]
      responses:
        "200":
          description: The merge job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeJob"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
    delete:
      tags: [Merges]
      operationId: cancelMerge
      summary: Cancel a queued merge job
      x-required-scopes: ["merges:write"]
      responses:
        "200":
          description: The job was cancelled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelledAck"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
        "409":
          description: The job is already running, completed, failed, or cancelled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/merges/{id}/requeue:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/JobId"
    post:
      tags: [Merges]
      operationId: requeueMerge
      summary: Requeue a dead-lettered merge job
      x-required-scopes: ["merges:write"]
      responses:
        "200":
          description: The requeued merge job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeJob"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/JobNotFound"
        "409":
          description: >-
            The job is not in `dead_letter` status, or an active merge job
            already exists for this source and target.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/rebase:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Merges]
      operationId: batchRebase
      summary: Rebase several branches onto a target ref
      description: |
        Runs synchronously and processes the branches sequentially; a conflict
        on one branch does not stop the rest. Ownership is not enforced.
      x-required-scopes: ["merges:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchRebaseRequest"
      responses:
        "200":
          description: Per-branch rebase results.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchRebaseResponse"
        "400":
          description: >-
            `target_ref` is missing, `branches` is empty, the workspace is not
            active, or the clone is not ready.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFound"
        "409":
          description: >-
            Another operation holds the workspace lock (`error_type:
            workspace_busy`). A rebuild holds it only during its fetch phase
            and final phase, not while it applies patches.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Batch rebase is not configured on this server, or the operation failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ---------------------------------------------------------------------------
  # Secrets
  # ---------------------------------------------------------------------------

  /api/v1/user/secrets:
    post:
      tags: [Secrets]
      operationId: createUserSecrets
      summary: Create user-scoped secrets
      description: |
        Secret values are stored base64-encoded and are **never** returned by
        the API -- responses carry key names and timestamps only.

        Validation: keys are alphanumeric plus underscore, must not start with
        a digit, and are at most 255 characters; values are at most 256 KB
        (262144 bytes); a scope holds at most 100 entries; key lookup is
        case-insensitive.
      x-required-scopes: ["secrets:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntriesRequest"
      responses:
        "201":
          $ref: "#/components/responses/SecretEntryList"
        "400":
          $ref: "#/components/responses/EntryValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "409":
          $ref: "#/components/responses/DuplicateKey"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Secrets]
      operationId: listUserSecrets
      summary: List user-scoped secrets
      description: Sorted by key, case-insensitively. Values are never returned.
      x-required-scopes: ["secrets:list", "secrets:manage"]
      responses:
        "200":
          $ref: "#/components/responses/SecretEntryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/secrets/{key}:
    parameters:
      - $ref: "#/components/parameters/EntryKey"
    patch:
      tags: [Secrets]
      operationId: updateUserSecret
      summary: Update a user-scoped secret value
      x-required-scopes: ["secrets:write", "secrets:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateValueRequest"
      responses:
        "200":
          $ref: "#/components/responses/SecretEntry"
        "400":
          $ref: "#/components/responses/MissingValueField"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/EntryNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Secrets]
      operationId: deleteUserSecret
      summary: Delete a user-scoped secret
      x-required-scopes: ["secrets:delete", "secrets:manage"]
      responses:
        "204":
          description: The secret was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/EntryNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{slug}/secrets:
    parameters:
      - $ref: "#/components/parameters/OrgSlug"
    post:
      tags: [Secrets]
      operationId: createOrgSecrets
      summary: Create organization-scoped secrets
      description: Requires organization membership; admin tokens bypass the check.
      x-required-scopes: ["secrets:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntriesRequest"
      responses:
        "201":
          $ref: "#/components/responses/SecretEntryList"
        "400":
          $ref: "#/components/responses/EntryValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/OrgNotFoundOrNotMember"
        "409":
          $ref: "#/components/responses/DuplicateKey"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Secrets]
      operationId: listOrgSecrets
      summary: List organization-scoped secrets
      x-required-scopes: ["secrets:list", "secrets:manage"]
      responses:
        "200":
          $ref: "#/components/responses/SecretEntryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/OrgNotFoundOrNotMember"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{slug}/secrets/{key}:
    parameters:
      - $ref: "#/components/parameters/OrgSlug"
      - $ref: "#/components/parameters/EntryKey"
    patch:
      tags: [Secrets]
      operationId: updateOrgSecret
      summary: Update an organization-scoped secret value
      x-required-scopes: ["secrets:write", "secrets:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateValueRequest"
      responses:
        "200":
          $ref: "#/components/responses/SecretEntry"
        "400":
          $ref: "#/components/responses/MissingValueField"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The organization was not found, the caller is not a member, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Secrets]
      operationId: deleteOrgSecret
      summary: Delete an organization-scoped secret
      x-required-scopes: ["secrets:delete", "secrets:manage"]
      responses:
        "204":
          description: The secret was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The organization was not found, the caller is not a member, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/secrets:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Secrets]
      operationId: createWorkspaceSecrets
      summary: Create workspace-scoped secrets
      description: Requires workspace ownership; admin tokens bypass the check.
      x-required-scopes: ["secrets:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntriesRequest"
      responses:
        "201":
          $ref: "#/components/responses/SecretEntryList"
        "400":
          $ref: "#/components/responses/EntryValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrNotOwned"
        "409":
          $ref: "#/components/responses/DuplicateKey"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Secrets]
      operationId: listWorkspaceSecrets
      summary: List workspace-scoped secrets
      x-required-scopes: ["secrets:list", "secrets:manage"]
      responses:
        "200":
          $ref: "#/components/responses/SecretEntryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrNotOwned"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/secrets/{key}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/EntryKey"
    patch:
      tags: [Secrets]
      operationId: updateWorkspaceSecret
      summary: Update a workspace-scoped secret value
      x-required-scopes: ["secrets:write", "secrets:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateValueRequest"
      responses:
        "200":
          $ref: "#/components/responses/SecretEntry"
        "400":
          $ref: "#/components/responses/MissingValueField"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The workspace was not found, is not owned by the caller, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Secrets]
      operationId: deleteWorkspaceSecret
      summary: Delete a workspace-scoped secret
      x-required-scopes: ["secrets:delete", "secrets:manage"]
      responses:
        "204":
          description: The secret was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The workspace was not found, is not owned by the caller, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Variables
  # ---------------------------------------------------------------------------

  /api/v1/user/vars:
    post:
      tags: [Variables]
      operationId: createUserVars
      summary: Create user-scoped variables
      description: |
        Variables use the same validation rules as secrets, but unlike secrets
        their values **are** returned by the API. Values are stored
        base64-encoded internally and returned decoded.
      x-required-scopes: ["vars:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntriesRequest"
      responses:
        "201":
          $ref: "#/components/responses/VariableEntryList"
        "400":
          $ref: "#/components/responses/EntryValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "409":
          $ref: "#/components/responses/DuplicateKey"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Variables]
      operationId: listUserVars
      summary: List user-scoped variables
      x-required-scopes: ["vars:read", "vars:write", "vars:manage"]
      responses:
        "200":
          $ref: "#/components/responses/VariableEntryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/vars/{key}:
    parameters:
      - $ref: "#/components/parameters/EntryKey"
    patch:
      tags: [Variables]
      operationId: updateUserVar
      summary: Update a user-scoped variable value
      x-required-scopes: ["vars:write", "vars:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateValueRequest"
      responses:
        "200":
          $ref: "#/components/responses/VariableEntry"
        "400":
          $ref: "#/components/responses/MissingValueField"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/EntryNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Variables]
      operationId: deleteUserVar
      summary: Delete a user-scoped variable
      x-required-scopes: ["vars:delete", "vars:manage"]
      responses:
        "204":
          description: The variable was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/EntryNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{slug}/vars:
    parameters:
      - $ref: "#/components/parameters/OrgSlug"
    post:
      tags: [Variables]
      operationId: createOrgVars
      summary: Create organization-scoped variables
      description: Requires organization membership; admin tokens bypass the check.
      x-required-scopes: ["vars:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntriesRequest"
      responses:
        "201":
          $ref: "#/components/responses/VariableEntryList"
        "400":
          $ref: "#/components/responses/EntryValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/OrgNotFoundOrNotMember"
        "409":
          $ref: "#/components/responses/DuplicateKey"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Variables]
      operationId: listOrgVars
      summary: List organization-scoped variables
      x-required-scopes: ["vars:read", "vars:write", "vars:manage"]
      responses:
        "200":
          $ref: "#/components/responses/VariableEntryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/OrgNotFoundOrNotMember"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{slug}/vars/{key}:
    parameters:
      - $ref: "#/components/parameters/OrgSlug"
      - $ref: "#/components/parameters/EntryKey"
    patch:
      tags: [Variables]
      operationId: updateOrgVar
      summary: Update an organization-scoped variable value
      x-required-scopes: ["vars:write", "vars:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateValueRequest"
      responses:
        "200":
          $ref: "#/components/responses/VariableEntry"
        "400":
          $ref: "#/components/responses/MissingValueField"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The organization was not found, the caller is not a member, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Variables]
      operationId: deleteOrgVar
      summary: Delete an organization-scoped variable
      x-required-scopes: ["vars:delete", "vars:manage"]
      responses:
        "204":
          description: The variable was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The organization was not found, the caller is not a member, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/vars:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    post:
      tags: [Variables]
      operationId: createWorkspaceVars
      summary: Create workspace-scoped variables
      description: |
        Requires workspace ownership; admin tokens bypass the check.

        Several variable keys change hub behaviour -- see the
        `WorkspaceVariables` schema for the recognised names.
      x-required-scopes: ["vars:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntriesRequest"
      responses:
        "201":
          $ref: "#/components/responses/VariableEntryList"
        "400":
          $ref: "#/components/responses/EntryValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrNotOwned"
        "409":
          $ref: "#/components/responses/DuplicateKey"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Variables]
      operationId: listWorkspaceVars
      summary: List workspace-scoped variables
      x-required-scopes: ["vars:read", "vars:write", "vars:manage"]
      responses:
        "200":
          $ref: "#/components/responses/VariableEntryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrNotOwned"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/vars/resolved:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Variables]
      operationId: listResolvedWorkspaceVars
      summary: Resolve variables across the user, org, and workspace tiers
      description: |
        Merges the three tiers with workspace overriding org, and org
        overriding user. Each entry reports the tier its value came from in
        `origin`. Sorted by key, case-insensitively.
      x-required-scopes: ["vars:read", "vars:write", "vars:manage"]
      responses:
        "200":
          description: The resolved variables.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ResolvedVariableEntry"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundOrNotOwned"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/vars/{key}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/EntryKey"
    patch:
      tags: [Variables]
      operationId: updateWorkspaceVar
      summary: Update a workspace-scoped variable value
      x-required-scopes: ["vars:write", "vars:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateValueRequest"
      responses:
        "200":
          $ref: "#/components/responses/VariableEntry"
        "400":
          $ref: "#/components/responses/MissingValueField"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The workspace was not found, is not owned by the caller, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Variables]
      operationId: deleteWorkspaceVar
      summary: Delete a workspace-scoped variable
      x-required-scopes: ["vars:delete", "vars:manage"]
      responses:
        "204":
          description: The variable was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/InsufficientScope"
        "404":
          description: The workspace was not found, is not owned by the caller, or the key is unknown.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Agent sessions
  # ---------------------------------------------------------------------------

  /api/v1/sessions:
    post:
      tags: [Sessions]
      operationId: createSession
      summary: Open an agent session
      description: |
        Records which credential and workspace an agent run is using.
        Idempotent on a client-provided `id`: an existing session is returned
        with `200` instead of `201`.
      x-required-scopes: ["sessions:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSessionRequest"
      responses:
        "200":
          description: A session with this `id` already exists; the existing record is returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
        "201":
          description: The session was opened.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
        "400":
          description: The body is malformed, or `workspace_slug` is missing or empty.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller lacks the `sessions:write` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Sessions]
      operationId: listSessions
      summary: List agent sessions
      description: |
        Keyset-paginated. Non-admin callers see only sessions in workspaces
        they own; admin tokens see every workspace.
      x-required-scopes: ["sessions:read"]
      parameters:
        - name: workspace_slug
          in: query
          schema: { type: string }
          description: Filter by workspace.
        - name: run_id
          in: query
          schema: { type: string }
          description: Filter by run identifier.
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/SessionStatus"
          description: Filter by session status.
        - name: credential_type
          in: query
          schema:
            type: string
            enum: [admin_token, api_key, pat]
          description: Filter by the credential type that opened the session.
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Order"
        - name: limit
          in: query
          description: Page size.
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of sessions, each including its `token_summary`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionListResponse"
        "400":
          description: The cursor is invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller lacks `sessions:read`, or workspace access was denied.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/sessions/{id}:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    get:
      tags: [Sessions]
      operationId: getSession
      summary: Get a session
      x-required-scopes: ["sessions:read"]
      responses:
        "200":
          description: The session, including its `token_summary`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller lacks `sessions:read`, or cannot access the session's workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: The session does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/sessions/{id}/complete:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    post:
      tags: [Sessions]
      operationId: completeSession
      summary: Close a session with a terminal status
      description: |
        The caller must own the session, or hold an admin token. Idempotent:
        completing an already-terminal session returns the existing record with
        `200`.

        `terminated` is reserved for server-initiated force-closes (workspace
        archive or delete) and is rejected as a client-supplied status.
      x-required-scopes: ["sessions:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteSessionRequest"
      responses:
        "200":
          description: The closed session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
        "400":
          description: The body is malformed, or `status` is `terminated` or otherwise invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller is neither the session owner nor an admin.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: The session does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: The session is not active (concurrent close).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/sessions/{id}/usage:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    post:
      tags: [Sessions]
      operationId: reportSessionUsage
      summary: Report incremental token usage
      description: The caller must own the session, or hold an admin token.
      x-required-scopes: ["sessions:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReportUsageRequest"
      responses:
        "201":
          description: The recorded token-usage entry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenUsage"
        "400":
          description: The body is malformed, or `model` is missing or empty.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller is neither the session owner nor an admin.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: The session does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: The session is not active.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: A token count is negative.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Sessions]
      operationId: listSessionUsage
      summary: List token-usage records for a session
      description: |
        `totals` always aggregates every record for the session, independent of
        the page being returned.
      x-required-scopes: ["sessions:read"]
      parameters:
        - $ref: "#/components/parameters/Order"
        - name: limit
          in: query
          description: Page size.
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of token-usage records plus unbounded totals.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageListResponse"
        "400":
          description: The cursor is invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller lacks `sessions:read`, or cannot access the session's workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: The session does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/cost:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
    get:
      tags: [Sessions]
      operationId: getWorkspaceCost
      summary: Aggregate token usage for a workspace
      x-required-scopes: ["sessions:read"]
      parameters:
        - name: group_by
          in: query
          description: Breakdown dimension.
          schema:
            type: string
            enum: [day, session, model]
            default: day
        - name: since
          in: query
          description: Start of the window. Defaults to 24 hours ago.
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          description: End of the window. Defaults to now.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Aggregated cost data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CostResponse"
        "400":
          description: "`since` is not before `until`, or `group_by` is invalid."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller lacks `sessions:read`, or cannot access the workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Audit ingestion (per run)
  # ---------------------------------------------------------------------------

  /api/v1/workspaces/{slug}/runs/{run_id}/events:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestAuditEvent
      summary: Ingest one audit event
      description: |
        Ingestion is idempotent: rows are written with `INSERT OR IGNORE`, so a
        duplicate `id` yields `200` instead of `201`.

        Write access is checked per request: a workspace-scoped PAT must match
        the URL `:slug` (`403 workspace_mismatch`), a generic PAT or API key
        must own the workspace (`403 workspace_access_denied`), and an archived
        workspace is rejected (`409 workspace_archived`). Admin tokens bypass
        all of these.
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostEventRequest"
      responses:
        "200":
          description: A row with this `id` already existed; nothing was written.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostEventResponse"
        "201":
          description: The event was ingested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostEventResponse"
        "400":
          description: >-
            `event_type` is missing, `run_id` is malformed, or the body `run_id`
            disagrees with the URL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Audit Ingestion]
      operationId: queryRunAuditEvents
      summary: Query audit events for a run
      description: Cursor-paginated. Ownership is not enforced for audit reads.
      x-required-scopes: ["audit:read"]
      parameters:
        - $ref: "#/components/parameters/FilterEventType"
        - $ref: "#/components/parameters/FilterSeverity"
        - $ref: "#/components/parameters/FilterNodeId"
        - $ref: "#/components/parameters/FilterSessionId"
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Until"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/AuditLimit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of audit events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunEventListResponse"
        "400":
          $ref: "#/components/responses/InvalidQueryParams"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/events/batch:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestAuditEventsBatch
      summary: Bulk-ingest up to 1000 audit events
      description: |
        The body is a JSON array of the same objects accepted by the single
        event endpoint. Per-item failures are reported in the `errors` array
        rather than failing the whole request.
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 1000
              items:
                $ref: "#/components/schemas/PostEventRequest"
      responses:
        "200":
          description: Per-item ingestion outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchIngestResponse"
        "400":
          description: The array is empty or the body is malformed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "413":
          description: More than 1000 items were submitted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/sessions/outcomes:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestSessionOutcome
      summary: Ingest one session outcome
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostSessionOutcomeRequest"
      responses:
        "200":
          description: A row with this `id` already existed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostSessionOutcomeResponse"
        "201":
          description: The outcome was ingested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostSessionOutcomeResponse"
        "400":
          description: A required field is missing, or `run_id` is malformed or mismatched.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Audit Ingestion]
      operationId: queryRunSessionOutcomes
      summary: Query session outcomes for a run
      x-required-scopes: ["audit:read"]
      parameters:
        - $ref: "#/components/parameters/FilterSessionId"
        - $ref: "#/components/parameters/FilterStatus"
        - $ref: "#/components/parameters/FilterNodeId"
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Until"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/AuditLimit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of session outcomes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunOutcomeListResponse"
        "400":
          $ref: "#/components/responses/InvalidQueryParams"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/tools/calls:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestToolCall
      summary: Ingest one tool call
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostToolCallRequest"
      responses:
        "200":
          description: A row with this `id` already existed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostToolCallResponse"
        "201":
          description: The tool call was ingested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostToolCallResponse"
        "400":
          description: "`tool_name` is missing, or `run_id` is malformed or mismatched."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Audit Ingestion]
      operationId: queryRunToolCalls
      summary: Query tool calls for a run
      x-required-scopes: ["audit:read"]
      parameters:
        - $ref: "#/components/parameters/FilterToolName"
        - $ref: "#/components/parameters/FilterSessionId"
        - $ref: "#/components/parameters/FilterNodeId"
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Until"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/AuditLimit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of tool calls.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunToolCallListResponse"
        "400":
          $ref: "#/components/responses/InvalidQueryParams"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/tools/errors:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestToolError
      summary: Ingest one tool error
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostToolErrorRequest"
      responses:
        "200":
          description: A row with this `id` already existed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostToolErrorResponse"
        "201":
          description: The tool error was ingested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostToolErrorResponse"
        "400":
          description: >-
            `tool_name` or `error_msg` is missing, or `run_id` is malformed or
            mismatched.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Audit Ingestion]
      operationId: queryRunToolErrors
      summary: Query tool errors for a run
      x-required-scopes: ["audit:read"]
      parameters:
        - $ref: "#/components/parameters/FilterToolName"
        - $ref: "#/components/parameters/FilterSessionId"
        - $ref: "#/components/parameters/FilterNodeId"
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Until"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/AuditLimit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of tool errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunToolErrorListResponse"
        "400":
          $ref: "#/components/responses/InvalidQueryParams"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/traces:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestTrace
      summary: Ingest one trace event
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostTraceRequest"
      responses:
        "200":
          description: A row with this `id` already existed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostTraceResponse"
        "201":
          description: The trace event was ingested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostTraceResponse"
        "400":
          description: "`event_type` is missing, or `run_id` is malformed or mismatched."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Audit Ingestion]
      operationId: queryRunTraces
      summary: Query trace events for a run
      x-required-scopes: ["audit:read"]
      parameters:
        - $ref: "#/components/parameters/FilterEventType"
        - $ref: "#/components/parameters/FilterSessionId"
        - $ref: "#/components/parameters/FilterNodeId"
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Until"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/AuditLimit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of trace events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunTraceListResponse"
        "400":
          $ref: "#/components/responses/InvalidQueryParams"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/traces/batch:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestTracesBatch
      summary: Bulk-ingest up to 1000 trace events
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 1000
              items:
                $ref: "#/components/schemas/PostTraceRequest"
      responses:
        "200":
          description: Per-item ingestion outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchIngestResponse"
        "400":
          description: The array is empty or the body is malformed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "413":
          description: More than 1000 items were submitted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/postmortem:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Audit Ingestion]
      operationId: ingestPostmortem
      summary: Submit a postmortem report
      description: At most one postmortem exists per `run_id`.
      x-required-scopes: ["audit:write"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostPostmortemRequest"
      responses:
        "200":
          description: A postmortem for this run already existed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostPostmortemResponse"
        "201":
          description: The postmortem was stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostPostmortemResponse"
        "400":
          description: A required field is missing, or `run_status` is invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AuditWriteForbidden"
        "409":
          $ref: "#/components/responses/WorkspaceArchived"
        "422":
          description: "Unsupported `schema_version` (`error_type: unknown_schema_version`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    get:
      tags: [Audit Ingestion]
      operationId: getPostmortem
      summary: Retrieve the postmortem for a run
      x-required-scopes: ["audit:read"]
      responses:
        "200":
          description: The postmortem record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Postmortem"
        "400":
          description: "`run_id` is malformed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "404":
          description: "No postmortem exists for this run (`error_type: postmortem_not_found`)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/workspaces/{slug}/runs/{run_id}/transcript:
    parameters:
      - $ref: "#/components/parameters/WorkspaceSlug"
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Audit Query]
      operationId: getRunTranscript
      summary: Reconstruct a conversation transcript
      description: |
        Rebuilds a conversation from the stored agent traces for one node of a
        run, mapping trace event types to roles: `session.init` becomes
        `system`, `assistant.message` becomes `assistant`, `tool.use` becomes
        `tool_use`, and `tool.error` becomes `tool_error`. Unrecognised trace
        types are skipped silently.
      x-required-scopes: ["audit:read"]
      parameters:
        - name: node_id
          in: query
          required: true
          description: The node within the run whose transcript should be rebuilt.
          schema:
            type: string
      responses:
        "200":
          description: The reconstructed transcript.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranscriptResponse"
        "400":
          description: The `node_id` query parameter is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Audit query and streaming
  # ---------------------------------------------------------------------------

  /api/v1/audit:
    get:
      tags: [Audit Query]
      operationId: queryUnifiedAudit
      summary: Unified audit event query
      description: |
        Merges `hub_audit_events` and `agent_audit_events` into one
        chronological result set with `UNION ALL`, newest first.

        Several filters are source-specific: `actor_id`, `actor_type`,
        `resource_type`, and `action` match hub events only (and therefore
        exclude agent events), while `run_id` matches agent events only.
      x-required-scopes: ["audit:read"]
      parameters:
        - name: source
          in: query
          description: Restrict to one event source.
          schema:
            type: string
            enum: [hub, agent]
        - name: workspace
          in: query
          description: Filter by workspace slug.
          schema: { type: string }
        - $ref: "#/components/parameters/FilterEventType"
        - name: event_type_prefix
          in: query
          description: >-
            Filter by event-type prefix, for example `hub.workspace` to match
            every workspace event.
          schema: { type: string }
        - $ref: "#/components/parameters/FilterSeverity"
        - name: actor_id
          in: query
          description: Filter by actor. Hub events only.
          schema: { type: string }
        - name: actor_type
          in: query
          description: Filter by actor credential type. Hub events only.
          schema: { type: string }
        - name: resource_type
          in: query
          description: Filter by affected resource type. Hub events only.
          schema: { type: string }
        - name: action
          in: query
          description: Filter by action. Hub events only.
          schema: { type: string }
        - name: run_id
          in: query
          description: Filter by agent run identifier. Agent events only.
          schema: { type: string }
        - $ref: "#/components/parameters/Since"
        - $ref: "#/components/parameters/Until"
        - name: limit
          in: query
          description: Maximum events to return; clamped to 1000.
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of unified audit events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnifiedAuditQueryResponse"
        "400":
          description: "The cursor is invalid, `since` or `until` is malformed, or `since >= until`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/events:
    get:
      tags: [Audit Query]
      operationId: streamAuditEvents
      summary: Stream audit events over SSE
      description: |
        Opens a `text/event-stream` connection that delivers audit events as
        they are emitted.

        Frames:

        ```
        event: heartbeat
        data: {"timestamp":"2026-09-01T12:00:00Z"}

        event: audit_event
        data: {"id":"...","event_type":"hub.workspace.create","timestamp":"...","workspace":"..."}
        ```

        An initial heartbeat confirms the connection, and further heartbeats
        follow every 30 seconds. A connection with no reads for 60 seconds is
        closed. Each client buffers up to 256 events; when the buffer is full
        the oldest event is dropped to make room.

        The concurrent connection ceiling comes from `AF_SSE_MAX_CONNECTIONS`
        (default 100); beyond it new connections receive `503`.
      x-required-scopes: ["audit:read"]
      parameters:
        - name: workspace
          in: query
          description: Only deliver events for this workspace slug.
          schema: { type: string }
        - name: run_id
          in: query
          description: Only deliver events for this agent run.
          schema: { type: string }
        - name: category
          in: query
          description: Only deliver events in this category.
          schema: { type: string }
      responses:
        "200":
          description: The event stream.
          content:
            text/event-stream:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/MissingScope"
        "503":
          description: The maximum number of concurrent SSE connections is already in use.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ---------------------------------------------------------------------------
  # Git smart HTTP
  # ---------------------------------------------------------------------------

  /git/{org}/{slug}.git/info/refs:
    parameters:
      - $ref: "#/components/parameters/GitOrg"
      - $ref: "#/components/parameters/GitSlug"
    get:
      tags: [Git]
      operationId: gitInfoRefs
      summary: Git ref advertisement (smart HTTP discovery)
      description: |
        The `.git` suffix is mandatory; a request without it is answered with
        `404`.

        Authentication is HTTP Basic: the username is ignored and the password
        must be a valid hub credential. API keys and admin tokens have implicit
        git access; PATs need `git:read` (for `git-upload-pack`) or `git:write`
        (for `git-receive-pack`).

        Ownership is enforced -- a caller who does not own the workspace gets a
        pkt-line `404`, so slugs cannot be enumerated. Admin-role API keys do
        **not** bypass this; only admin tokens do.
      security:
        - gitBasicAuth: []
      x-required-scopes: ["git:read", "git:write"]
      parameters:
        - name: service
          in: query
          required: true
          description: The git service being negotiated.
          schema:
            type: string
            enum: [git-upload-pack, git-receive-pack]
      responses:
        "200":
          description: >-
            A pkt-line ref advertisement, with content type
            `application/x-<service>-advertisement`.
          content:
            application/x-git-upload-pack-advertisement:
              schema:
                type: string
                format: binary
            application/x-git-receive-pack-advertisement:
              schema:
                type: string
                format: binary
        "401":
          description: The credentials are missing or invalid.
        "403":
          description: >-
            The `service` parameter is missing or invalid, or the PAT lacks the
            required git scope. The body is a pkt-line error.
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: >-
            The workspace does not exist, the org does not match, the clone is
            not ready, the caller does not own the workspace, or the path lacks
            the `.git` suffix.

  /git/{org}/{slug}.git/git-upload-pack:
    parameters:
      - $ref: "#/components/parameters/GitOrg"
      - $ref: "#/components/parameters/GitSlug"
    post:
      tags: [Git]
      operationId: gitUploadPack
      summary: Git fetch and clone data transfer
      security:
        - gitBasicAuth: []
      x-required-scopes: ["git:read"]
      requestBody:
        required: true
        content:
          application/x-git-upload-pack-request:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: The pkt-line upload-pack result.
          content:
            application/x-git-upload-pack-result:
              schema:
                type: string
                format: binary
        "401":
          description: The credentials are missing or invalid.
        "403":
          description: The PAT lacks the `git:read` scope.
        "404":
          description: >-
            The workspace does not exist, the org does not match, the clone is
            not ready, or the caller does not own the workspace.

  /git/{org}/{slug}.git/git-receive-pack:
    parameters:
      - $ref: "#/components/parameters/GitOrg"
      - $ref: "#/components/parameters/GitSlug"
    post:
      tags: [Git]
      operationId: gitReceivePack
      summary: Git push data transfer
      description: |
        After a successful push the server updates `head_sha` in the database
        and resets the working tree to the new HEAD, then emits a
        `hub.git.push` audit event. Only accepted ref updates drive the audit
        event and the post-push hook.

        For carry-patch workspaces, a pre-receive hook enforces push control
        on registered patch branches. The behaviour depends on
        `PATCH_BRANCH_SOURCE` and `PUSH_PATCHES_TO_ORIGIN`:

        - **Reject** (`PATCH_BRANCH_SOURCE=origin`, `PUSH_PATCHES_TO_ORIGIN`
          not `"true"`): the update is rejected with a per-ref message naming
          the fork.
        - **Forward** (`PATCH_BRANCH_SOURCE=origin`,
          `PUSH_PATCHES_TO_ORIGIN=true`): the update is pushed to the fork
          before the hub writes its ref. A forward failure rejects the ref.
        - **Mirror** (`PATCH_BRANCH_SOURCE=hub`,
          `PUSH_PATCHES_TO_ORIGIN=true`): accepted pushes are force-pushed to
          the fork after the push, best effort.

        If a pushed branch is a registered patch of a carry-patch workspace and
        `AUTO_REBUILD_AFTER_PUSH` is not `"false"`, a rebuild job is enqueued.
        The hook runs asynchronously and never alters the push response.
      security:
        - gitBasicAuth: []
      x-required-scopes: ["git:write"]
      requestBody:
        required: true
        content:
          application/x-git-receive-pack-request:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: The pkt-line receive-pack result.
          content:
            application/x-git-receive-pack-result:
              schema:
                type: string
                format: binary
        "401":
          description: The credentials are missing or invalid.
        "403":
          description: The PAT lacks the `git:write` scope.
        "404":
          description: >-
            The workspace does not exist, the org does not match, the clone is
            not ready, or the caller does not own the workspace.

  # ---------------------------------------------------------------------------
  # Identity and access (apikit)
  #
  # Mounted by apikit's Server.MountHandlers on the API group, so every one of
  # these routes lives under the configured mount point -- `/api/v1` by
  # default. Both docs/api.md and docs/permissions.md write them without that
  # prefix; see docs/errata/openapi_description.md.
  # ---------------------------------------------------------------------------

  /version:
    get:
      tags: [Health]
      operationId: getVersion
      summary: Server build information
      description: >-
        Registered at the server root alongside the health probes, outside the
        API auth group. Cached publicly.
      security: []
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: Build metadata and the configured API mount point.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VersionResponse"

  /api/v1/auth/providers:
    get:
      tags: [Identity]
      operationId: listOAuthProviders
      summary: List the configured OAuth providers
      description: |
        Returns each provider configured under `[[oauth.providers]]` with the
        authorize URL to send the user to. Cached publicly for five minutes.

        Public: `RegisterOAuthHandlers` runs before `api.Use(authMiddleware)`
        in `MountHandlers`, and Echo snapshots a group's middleware when a
        route is added, so both `/auth` routes are registered without the auth
        middleware.
      security: []
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The configured providers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OAuthProvider"

  /api/v1/auth/callback:
    post:
      tags: [Identity]
      operationId: oauthCallback
      summary: Exchange an OAuth authorization code for an API key
      description: |
        The only way an API key is created. In a single transaction the hub
        upserts the user record, revokes **all** of that user's existing API
        keys, and generates a new `af_<key_id>_<secret>`. The plaintext key is
        returned once; only its SHA-256 hash is persisted.

        Public, like `GET /api/v1/auth/providers` -- it has to be reachable
        before the caller holds a credential.

        Because re-login mass-revokes keys, any automation still holding an
        older key for the same user stops working after a login.

        `redirect_uri` is validated against the provider's allowlist. `expires`
        is a key lifetime in days and must be 0, 30, 60, or 90; it defaults to
        90.

        On a new user the hub's `OnAfterUserCreate` hook runs inside the same
        transaction and creates the user's personal organization.
      security: []
      x-provider: apikit
      x-required-scopes: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OAuthCallbackRequest"
      responses:
        "200":
          description: The user record and the newly issued API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthCallbackResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: The authorization code is invalid or expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The matched user is blocked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: The user already exists under a conflicting identity.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user:
    get:
      tags: [Identity]
      operationId: getCurrentUser
      summary: Get the authenticated user's profile
      x-provider: apikit
      x-required-scopes: ["users:read"]
      responses:
        "200":
          $ref: "#/components/responses/UserProfile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    patch:
      tags: [Identity]
      operationId: updateCurrentUser
      summary: Update the authenticated user's profile
      description: "`full_name` is the only mutable field, and it is required."
      x-provider: apikit
      x-required-scopes: ["users:read"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          $ref: "#/components/responses/UserProfile"
        "400":
          description: The body is malformed, or `full_name` is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/orgs:
    get:
      tags: [Identity]
      operationId: listCurrentUserOrgs
      summary: List the authenticated user's organization memberships
      x-provider: apikit
      x-required-scopes: ["orgs:read"]
      responses:
        "200":
          description: The organizations the caller belongs to.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Organization"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/keys:
    get:
      tags: [Identity]
      operationId: listCurrentUserKeys
      summary: List the authenticated user's API keys
      description: >-
        Metadata only. Secret hashes, expiry-day settings, and plaintext
        secrets are never exposed. Supports conditional GET via ETag.
      x-provider: apikit
      x-required-scopes: ["keys:read"]
      responses:
        "200":
          description: The caller's API key metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKeyMeta"
        "304":
          description: The ETag matched; the listing is unchanged.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/keys/{key_id}:
    parameters:
      - $ref: "#/components/parameters/KeyId"
    delete:
      tags: [Identity]
      operationId: revokeCurrentUserKey
      summary: Revoke one of the authenticated user's API keys
      description: >-
        Self-revocation is allowed: the auth middleware validates the
        credential before the handler runs and does not re-validate mid-flight,
        so a key can revoke itself.
      x-provider: apikit
      x-required-scopes: ["keys:manage"]
      responses:
        "204":
          description: The key was revoked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: The key does not exist or belongs to another user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/keys/{key_id}/refresh:
    parameters:
      - $ref: "#/components/parameters/KeyId"
    post:
      tags: [Identity]
      operationId: refreshCurrentUserKey
      summary: Rotate an API key secret
      description: >-
        Generates a new secret while preserving `key_id`, and recomputes the
        expiry from the key's stored lifetime. **PAT authentication is
        rejected** -- this endpoint requires API key auth.
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The rotated key. The plaintext value is returned only here.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyFull"
        "400":
          description: The key is revoked or already expired and cannot be refreshed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: >-
            No credential was supplied, or the request authenticated with
            something other than an API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: The key does not exist or belongs to another user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/tokens:
    get:
      tags: [Identity]
      operationId: listCurrentUserTokens
      summary: List the authenticated user's personal access tokens
      x-provider: apikit
      x-required-scopes: ["tokens:read"]
      responses:
        "200":
          description: PAT metadata, including the permissions granted to each token.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PersonalAccessToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The PAT lacks the `tokens:read` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags: [Identity]
      operationId: createCurrentUserToken
      summary: Create a personal access token
      description: |
        Every requested permission is validated against the registry: a
        malformed scope or one that is not registered is rejected with `400`.

        A PAT creating another PAT may only grant permissions it already holds;
        attempting to exceed them fails with `403`. API keys are not subject to
        that restriction and may mint a PAT with any registered permission.
      x-provider: apikit
      x-required-scopes: ["tokens:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTokenRequest"
      responses:
        "201":
          description: The new token. The plaintext value is returned only here.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonalAccessTokenWithSecret"
        "400":
          description: >-
            The body is malformed; `name` is missing or over 255 characters;
            `permissions` is empty; a permission is malformed or unknown; or
            `expires` is not 0, 30, 60, or 90.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: >-
            The caller lacks `tokens:manage`, or a PAT tried to grant a
            permission it does not itself hold.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/tokens/{token_id}:
    parameters:
      - $ref: "#/components/parameters/TokenId"
    get:
      tags: [Identity]
      operationId: getCurrentUserToken
      summary: Get one of the authenticated user's PATs
      x-provider: apikit
      x-required-scopes: ["tokens:read"]
      responses:
        "200":
          description: The PAT metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonalAccessToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The PAT lacks the `tokens:read` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/TokenNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Identity]
      operationId: revokeCurrentUserToken
      summary: Revoke one of the authenticated user's PATs
      x-provider: apikit
      x-required-scopes: ["tokens:manage"]
      responses:
        "200":
          description: The revoked token's metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonalAccessToken"
        "400":
          description: The token is already revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The PAT lacks the `tokens:manage` scope.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/TokenNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/user/tokens/{token_id}/permissions:
    parameters:
      - $ref: "#/components/parameters/TokenId"
    put:
      tags: [Identity]
      operationId: replaceTokenPermissions
      summary: Replace a PAT's permissions
      description: >-
        An explicit empty array clears every permission and auto-revokes the
        token. An absent or null `permissions` field is rejected.
      x-provider: apikit
      x-required-scopes: ["tokens:write", "tokens:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PermissionsRequest"
      responses:
        "200":
          $ref: "#/components/responses/TokenPermissions"
        "400":
          description: The body is malformed, `permissions` is absent, or the token is revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/TokenPermissionForbidden"
        "404":
          $ref: "#/components/responses/TokenNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    patch:
      tags: [Identity]
      operationId: addTokenPermissions
      summary: Add permissions to a PAT
      description: An empty `permissions` array is an error here, unlike on `PUT`.
      x-provider: apikit
      x-required-scopes: ["tokens:write", "tokens:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PermissionsRequest"
      responses:
        "200":
          $ref: "#/components/responses/TokenPermissions"
        "400":
          description: >-
            The body is malformed, `permissions` is absent or empty, or the
            token is revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/TokenPermissionForbidden"
        "404":
          $ref: "#/components/responses/TokenNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Identity]
      operationId: removeTokenPermissions
      summary: Remove permissions from a PAT
      description: An empty `permissions` array is an error here, unlike on `PUT`.
      x-provider: apikit
      x-required-scopes: ["tokens:write", "tokens:manage"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PermissionsRequest"
      responses:
        "200":
          $ref: "#/components/responses/TokenPermissions"
        "400":
          description: >-
            The body is malformed, `permissions` is absent or empty, or the
            token is revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/TokenPermissionForbidden"
        "404":
          $ref: "#/components/responses/TokenNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # ---------------------------------------------------------------------------
  # Administration (apikit)
  #
  # Admin tokens and admin-role API keys only. Note the asymmetry: an
  # admin-role API key passes RequireAdmin here, but is treated as an ordinary
  # user by the workspace and git subsystems, which check for the admin token
  # credential type directly.
  # ---------------------------------------------------------------------------

  /api/v1/users:
    get:
      tags: [Administration]
      operationId: listUsers
      summary: List all users
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: Every user on the server.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags: [Administration]
      operationId: createUser
      summary: Create a user
      description: >-
        The INSERT and the after-user-create hook run in one transaction, so
        the hub's personal-organization creation is atomic with the user
        record.
      x-provider: apikit
      x-required-scopes: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: The created user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: The body is malformed or a required field is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "409":
          description: The username or the provider identity already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}:
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: [Administration]
      operationId: getUser
      summary: Get any user
      description: Supports conditional GET via ETag.
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "304":
          description: The ETag matched; the record is unchanged.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    patch:
      tags: [Administration]
      operationId: updateUser
      summary: Update any user
      description: "`full_name` is the only mutable field, and it is required."
      x-provider: apikit
      x-required-scopes: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: The body is malformed, or `full_name` is missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/promote:
    parameters:
      - $ref: "#/components/parameters/UserId"
    post:
      tags: [Administration]
      operationId: promoteUser
      summary: Promote a user to admin
      description: Idempotent -- promoting an existing admin returns the record unchanged.
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The promoted user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/demote:
    parameters:
      - $ref: "#/components/parameters/UserId"
    post:
      tags: [Administration]
      operationId: demoteUser
      summary: Demote a user from admin
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The demoted user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "409":
          description: The last remaining admin cannot be demoted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/block:
    parameters:
      - $ref: "#/components/parameters/UserId"
    post:
      tags: [Administration]
      operationId: blockUser
      summary: Block a user
      description: >-
        Blocking disables every API key the user owns at authentication time
        without revoking them individually; unblocking re-enables all
        non-revoked, unexpired keys.
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The blocked user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/unblock:
    parameters:
      - $ref: "#/components/parameters/UserId"
    post:
      tags: [Administration]
      operationId: unblockUser
      summary: Unblock a user
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The unblocked user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/keys:
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: [Administration]
      operationId: listUserKeys
      summary: List any user's API keys
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The user's API key metadata, including the owning `user_id`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKeyMetaWithOwner"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/keys/{key_id}:
    parameters:
      - $ref: "#/components/parameters/UserId"
      - $ref: "#/components/parameters/KeyId"
    delete:
      tags: [Administration]
      operationId: revokeUserKey
      summary: Revoke any user's API key
      x-provider: apikit
      x-required-scopes: []
      responses:
        "204":
          description: The key was revoked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          description: The user or the key does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/tokens:
    parameters:
      - $ref: "#/components/parameters/UserId"
    get:
      tags: [Administration]
      operationId: listUserTokens
      summary: List any user's PATs
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The user's PAT metadata, including the owning `user_id`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PersonalAccessTokenWithOwner"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/UserNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/users/{id}/tokens/{token_id}:
    parameters:
      - $ref: "#/components/parameters/UserId"
      - $ref: "#/components/parameters/TokenId"
    delete:
      tags: [Administration]
      operationId: revokeUserToken
      summary: Revoke any user's PAT
      x-provider: apikit
      x-required-scopes: []
      responses:
        "204":
          description: The token was revoked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          description: The user or the token does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs:
    get:
      tags: [Administration]
      operationId: listOrgs
      summary: List all organizations
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: Every organization on the server.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Organization"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags: [Administration]
      operationId: createOrg
      summary: Create an organization
      description: >-
        Each user additionally receives a personal organization automatically
        on creation, through the hub's `OnAfterUserCreate` hook.
      x-provider: apikit
      x-required-scopes: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrgRequest"
      responses:
        "201":
          description: The created organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "400":
          description: The body is malformed, `name` or `slug` is missing, or the slug format is invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "409":
          description: The organization name or slug already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{id}:
    parameters:
      - $ref: "#/components/parameters/OrgId"
    get:
      tags: [Administration]
      operationId: getOrg
      summary: Get an organization
      description: >-
        Non-admin callers must be a member; admin credentials bypass that
        check. Supports conditional GET via ETag.
      x-provider: apikit
      x-required-scopes: ["orgs:read"]
      responses:
        "200":
          description: The organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "304":
          description: The ETag matched; the record is unchanged.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The caller is not a member of the organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/OrgNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    patch:
      tags: [Administration]
      operationId: updateOrg
      summary: Update an organization
      description: "`name` and `url` are the mutable fields; at least one must be supplied."
      x-provider: apikit
      x-required-scopes: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateOrgRequest"
      responses:
        "200":
          description: The updated organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "400":
          description: The body is malformed, no fields were supplied, or `name` was set to empty.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/OrgNotFound"
        "409":
          description: The organization name already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Administration]
      operationId: deleteOrg
      summary: Delete an organization
      x-provider: apikit
      x-required-scopes: []
      responses:
        "204":
          description: The organization was deleted.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/OrgNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{id}/block:
    parameters:
      - $ref: "#/components/parameters/OrgId"
    post:
      tags: [Administration]
      operationId: blockOrg
      summary: Block an organization
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The blocked organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/OrgNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{id}/unblock:
    parameters:
      - $ref: "#/components/parameters/OrgId"
    post:
      tags: [Administration]
      operationId: unblockOrg
      summary: Unblock an organization
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The unblocked organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/OrgNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{id}/members:
    parameters:
      - $ref: "#/components/parameters/OrgId"
    get:
      tags: [Administration]
      operationId: listOrgMembers
      summary: List organization members
      description: Admin credentials bypass the membership check.
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The organization's members.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OrgMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          $ref: "#/components/responses/OrgNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v1/orgs/{id}/members/{user_id}:
    parameters:
      - $ref: "#/components/parameters/OrgId"
      - name: user_id
        in: path
        required: true
        description: The user to add or remove.
        schema:
          type: string
          format: uuid
    put:
      tags: [Administration]
      operationId: addOrgMember
      summary: Add a member to an organization
      x-provider: apikit
      x-required-scopes: []
      responses:
        "200":
          description: The membership record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrgMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          description: The organization or the user does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Administration]
      operationId: removeOrgMember
      summary: Remove a member from an organization
      x-provider: apikit
      x-required-scopes: []
      responses:
        "204":
          description: The user is no longer a member.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/AdminRequired"
        "404":
          description: The organization or the membership does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalServerError"

# =============================================================================
# Components
# =============================================================================

components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        `Authorization: Bearer <credential>`, where the credential is an admin
        token (`af_admin_<64-hex>`), an API key (`af_<key_id>_<secret>`), or a
        personal access token (`af_pat_<token_id>_<secret>`).
    gitBasicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic authentication for the git smart HTTP endpoints. The
        username is ignored; the password must be a valid hub credential.
        `afc credential-helper get` returns the stored API key with the
        username `x-token-auth`.

  parameters:

    WorkspaceSlug:
      name: slug
      in: path
      required: true
      description: The workspace slug.
      schema:
        $ref: "#/components/schemas/Slug"

    OrgSlug:
      name: slug
      in: path
      required: true
      description: The organization slug.
      schema:
        type: string

    OrgId:
      name: id
      in: path
      required: true
      description: The organization identifier.
      schema:
        type: string

    UserId:
      name: id
      in: path
      required: true
      description: The user identifier.
      schema:
        type: string
        format: uuid

    KeyId:
      name: key_id
      in: path
      required: true
      description: The API key identifier (the `key_id` segment of the key).
      schema:
        type: string

    TokenId:
      name: token_id
      in: path
      required: true
      description: The personal access token identifier.
      schema:
        type: string

    PatchId:
      name: id
      in: path
      required: true
      description: The patch identifier.
      schema:
        type: string
        format: uuid

    JobId:
      name: id
      in: path
      required: true
      description: The job identifier.
      schema:
        type: string
        format: uuid

    SessionId:
      name: id
      in: path
      required: true
      description: The agent session identifier.
      schema:
        type: string

    EntryKey:
      name: key
      in: path
      required: true
      description: The secret or variable key. Lookup is case-insensitive.
      schema:
        $ref: "#/components/schemas/EntryKeyName"

    RunId:
      name: run_id
      in: path
      required: true
      description: The agent run identifier.
      schema:
        $ref: "#/components/schemas/RunId"

    GitOrg:
      name: org
      in: path
      required: true
      description: The organization slug that owns the workspace.
      schema:
        type: string

    GitSlug:
      name: slug
      in: path
      required: true
      description: >-
        The workspace slug. The literal `.git` suffix that follows it in the
        path is required and is not part of this value.
      schema:
        $ref: "#/components/schemas/Slug"

    Since:
      name: since
      in: query
      description: Inclusive lower bound on the record timestamp.
      schema:
        type: string
        format: date-time

    Until:
      name: until
      in: query
      description: Exclusive upper bound on the record timestamp.
      schema:
        type: string
        format: date-time

    Order:
      name: order
      in: query
      description: Sort order.
      schema:
        type: string
        enum: [asc, desc]
        default: desc

    Cursor:
      name: cursor
      in: query
      description: Opaque base64url keyset pagination token from a previous response.
      schema:
        type: string

    AuditLimit:
      name: limit
      in: query
      description: Page size.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 500

    FilterEventType:
      name: event_type
      in: query
      description: Filter by exact event type.
      schema:
        type: string

    FilterSeverity:
      name: severity
      in: query
      description: Filter by severity.
      schema:
        $ref: "#/components/schemas/Severity"

    FilterNodeId:
      name: node_id
      in: query
      description: Filter by task-graph node identifier.
      schema:
        type: string

    FilterSessionId:
      name: session_id
      in: query
      description: Filter by session identifier.
      schema:
        type: string

    FilterToolName:
      name: tool_name
      in: query
      description: Filter by tool name.
      schema:
        type: string

    FilterStatus:
      name: status
      in: query
      description: Filter by status.
      schema:
        type: string

  responses:

    Unauthorized:
      description: No credential was supplied, or the credential is invalid, revoked, or expired.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: 401
              message: authentication required

    MissingScope:
      description: The PAT lacks a permission scope required by this endpoint.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    InsufficientScope:
      description: >-
        The PAT lacks a permission scope required by this endpoint
        (`insufficient permission scope`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    AdminRequired:
      description: The credential is not an admin token or an admin-role API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    BadRequest:
      description: The request body is missing or malformed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    InternalServerError:
      description: An unexpected server-side failure, typically a database error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    WorkspaceNotFound:
      description: No workspace with this slug exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    WorkspaceNotFoundOrForbidden:
      description: >-
        The workspace does not exist, is not owned by the caller, or the PAT
        lacks the required scope. All three collapse to `404` under the
        anti-enumeration policy.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    WorkspaceNotFoundOrNotOwned:
      description: The workspace does not exist or is not owned by the caller.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    OrgNotFound:
      description: No organization with this identifier exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    OrgNotFoundOrNotMember:
      description: The organization does not exist, or the caller is not a member.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    UserNotFound:
      description: No user with this identifier exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    PatchNotFound:
      description: No patch with this identifier exists for the given workspace.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    JobNotFound:
      description: The job does not exist, or it belongs to a different workspace.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    EntryNotFound:
      description: No entry with this key exists in the scope.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    DuplicateKey:
      description: An entry with this key already exists in the scope (case-insensitive).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    MissingValueField:
      description: The request body does not contain a `value` field.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    EntryValidationError:
      description: >-
        `entries` is empty, a key has an invalid format or is too long, a value
        exceeds 256 KB, or the 100-entry per-scope limit would be exceeded.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    InvalidQueryParams:
      description: The cursor is invalid, or `since` or `until` is not a valid RFC 3339 timestamp.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    AuditWriteForbidden:
      description: >-
        A workspace-scoped PAT does not match the URL slug
        (`error_type: workspace_mismatch`), or the caller has no write access to
        the workspace (`error_type: workspace_access_denied`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    WorkspaceArchived:
      description: "The workspace is archived and rejects ingestion (`error_type: workspace_archived`)."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    SecretEntry:
      description: A secret entry. The value is never included.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SecretEntry"

    SecretEntryList:
      description: Secret entries. Values are never included.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/SecretEntry"

    VariableEntry:
      description: A variable entry, including its decoded value.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/VariableEntry"

    VariableEntryList:
      description: Variable entries, including their decoded values.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/VariableEntry"

    UserProfile:
      description: The user profile.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"

    TokenPermissions:
      description: The token's metadata, including its permissions after the change.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PersonalAccessToken"

    TokenNotFound:
      description: The token does not exist or belongs to another user.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    TokenPermissionForbidden:
      description: >-
        The caller lacks `tokens:write` or `tokens:manage`, or a PAT tried to
        grant a permission it does not itself hold.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:

    # -- Shared primitives -----------------------------------------------------

    Error:
      type: object
      description: The apikit error envelope used by every error response.
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: integer
              description: The HTTP status code, repeated in the body.
            message:
              type: string
              description: A human-readable description of the failure.
            error_type:
              type: string
              description: >-
                Machine-readable classification. Present only on the handlers
                that set it.
              enum:
                - duplicate_merge
                - workspace_mode_mismatch
                - no_active_patches
                - concurrent_rebuild
                - workspace_mismatch
                - workspace_access_denied
                - workspace_archived
                - unknown_schema_version
                - postmortem_not_found
      examples:
        - error:
            code: 400
            message: slug is required
        - error:
            code: 409
            message: a rebuild job is already queued or running for this workspace
            error_type: concurrent_rebuild

    Slug:
      type: string
      description: |
        A URL-safe identifier: 3-64 characters, starting with a lowercase
        letter, ending with a lowercase letter or digit, containing only
        lowercase letters, digits, and hyphens, with no consecutive hyphens.
      minLength: 3
      maxLength: 64
      pattern: "^[a-z](?:[a-z0-9]|-(?!-))*[a-z0-9]$"
      examples: [my-project]

    EntryKeyName:
      type: string
      description: >-
        A secret or variable key: alphanumeric characters and underscores only,
        not starting with a digit, at most 255 characters. Lookup is
        case-insensitive.
      maxLength: 255
      pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
      examples: [MY_SECRET]

    RunId:
      type: string
      description: An agent run identifier, formatted `YYYYMMDD_HHMMSS_<6 hex chars>`.
      pattern: "^[0-9]{8}_[0-9]{6}_[0-9a-f]{6}$"
      examples: ["20260704_143022_a1b2c3"]

    Sha:
      type: string
      description: A 40-character lowercase hex git object SHA.
      pattern: "^[0-9a-f]{40}$"

    Severity:
      type: string
      enum: [info, warning, error, critical]

    JobStatus:
      type: string
      description: Durable job queue lifecycle state.
      enum: [queued, running, completed, failed, dead_letter, cancelled]

    SessionStatus:
      type: string
      description: >-
        Agent session state. `terminated` is set only by the server when a
        workspace is archived or deleted; clients cannot set it.
      enum: [active, completed, failed, timeout, terminated]

    PatchStatus:
      type: string
      enum: [active, merged_upstream, conflict, disabled, deleted]

    # -- Workspaces ------------------------------------------------------------

    Workspace:
      type: object
      description: |
        A unit of work with its own clone, branch, and agents. Every field is
        always present in the response; nullable fields are emitted as `null`
        rather than omitted.
      required:
        - slug
        - git_url
        - hub_url
        - branch
        - owner_id
        - org_id
        - status
        - display_name
        - description
        - clone_status
        - head_sha
        - clone_error
        - created_at
        - updated_at
        - sync_mode
        - sync_status
        - upstream_head_sha
        - last_sync_at
        - sync_error
        - workspace_mode
        - upstream_url
        - integration_branch
      properties:
        slug:
          allOf:
            - $ref: "#/components/schemas/Slug"
          description: Immutable, globally unique identifier.
        git_url:
          type: string
          description: HTTPS or SSH URL of the git repository. Immutable after creation.
        hub_url:
          type: [string, "null"]
          description: >-
            Clone URL on the built-in git server. Null when `server.external_url`
            is unconfigured or the workspace has no organization.
          examples: ["http://localhost:8080/git/org-slug/my-project.git"]
        branch:
          type: [string, "null"]
          description: Git ref associated with the workspace. Immutable after creation.
        owner_id:
          type: string
          format: uuid
          description: The user who owns the workspace.
        org_id:
          type: [string, "null"]
          format: uuid
          description: The organization the workspace belongs to.
        status:
          type: string
          enum: [active, archived]
        display_name:
          type: string
          description: >-
            Human-readable label. Defaults to the slug when unset; never null or
            empty.
          maxLength: 128
        description:
          type: string
          description: Free-form text. Defaults to an empty string; never null.
          maxLength: 1024
        clone_status:
          type: string
          enum: [pending, cloning, ready, failed, archived]
        head_sha:
          oneOf:
            - $ref: "#/components/schemas/Sha"
            - type: "null"
          description: >-
            HEAD commit of the local clone. Set when `clone_status` is `ready`
            or `archived`.
        clone_error:
          type: [string, "null"]
          description: Failure detail when `clone_status` is `failed`.
        sync_mode:
          type: string
          enum: [pull_only, disabled]
          default: pull_only
        sync_status:
          type: string
          enum: [idle, syncing, error]
          default: idle
        upstream_head_sha:
          oneOf:
            - $ref: "#/components/schemas/Sha"
            - type: "null"
          description: Upstream HEAD at the last fetch. Null until the first sync.
        last_sync_at:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last successful sync.
        sync_error:
          type: [string, "null"]
          description: Failure detail from the most recent failed sync.
        workspace_mode:
          type: string
          enum: [standard, carry_patch]
          default: standard
          description: >-
            `standard` is single-remote; `carry_patch` is dual-remote with a
            patch list. Immutable after creation.
        upstream_url:
          type: [string, "null"]
          description: >-
            Upstream repository for carry-patch workspaces. Null for standard
            workspaces; immutable after creation.
        integration_branch:
          type: [string, "null"]
          description: >-
            The mechanically rebuilt branch combining the upstream base with all
            carried patches. Defaults to `deploy` for carry-patch workspaces and
            is null for standard ones; immutable after creation.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateWorkspaceRequest:
      type: object
      required: [slug, git_url]
      properties:
        slug:
          $ref: "#/components/schemas/Slug"
        git_url:
          type: string
          description: A valid HTTPS or SSH git URL.
        branch:
          type: [string, "null"]
        org_id:
          type: [string, "null"]
          description: >-
            Must reference an organization the owner belongs to (by UUID or slug).
            When omitted or empty, the caller's personal organization is assigned.
        display_name:
          type: [string, "null"]
          maxLength: 128
          description: Defaults to the slug when omitted or empty.
        description:
          type: [string, "null"]
          maxLength: 1024
          description: Defaults to an empty string.
        sync_mode:
          type: [string, "null"]
          enum: [pull_only, disabled, null]
          default: pull_only
        workspace_mode:
          type: [string, "null"]
          enum: [standard, carry_patch, null]
          default: standard
        upstream_url:
          type: [string, "null"]
          description: >-
            Required when `workspace_mode` is `carry_patch`; rejected for
            standard workspaces.
        integration_branch:
          type: [string, "null"]
          description: >-
            Defaults to `deploy` for carry-patch workspaces; rejected for
            standard workspaces.
        git_pat:
          type: string
          format: password
          description: >-
            Personal access token for a private repository. Mutually exclusive
            with `git_username`/`git_password` and requires an HTTPS `git_url`.
        git_username:
          type: string
          description: >-
            HTTP basic auth username. Must be paired with `git_password`,
            mutually exclusive with `git_pat`, and requires an HTTPS `git_url`.
        git_password:
          type: string
          format: password
          description: HTTP basic auth password. Must be paired with `git_username`.

    UpdateWorkspaceRequest:
      type: object
      description: >-
        Partial update. Only the properties present in the body are modified;
        at least one must be supplied. Sending an immutable field is rejected.
      minProperties: 1
      properties:
        display_name:
          type: [string, "null"]
          maxLength: 128
          description: "`null` resets the display name to the workspace slug."
        description:
          type: [string, "null"]
          maxLength: 1024
          description: "`null` clears the description to an empty string."
        org_id:
          type: [string, "null"]
          description: >-
            Must reference an organization the owner belongs to (by UUID or slug).
            `null` removes the association.
        sync_mode:
          type: string
          enum: [pull_only, disabled]
          description: "`null` is rejected with `400`."
      additionalProperties: false

    CarryPatchSyncResponse:
      type: object
      description: |
        Returned by `POST /api/v1/workspaces/{slug}/sync` when the workspace is
        in `carry_patch` mode: the full workspace object plus the carry-patch
        fields as additional top-level keys (16-REQ-5.1).
      allOf:
        - $ref: "#/components/schemas/Workspace"
      required: [patches_merged, rebuild_triggered, force_push_detected, origin_fetched]
      properties:
        patches_merged:
          type: array
          description: >-
            Branch names of patches detected as merged upstream, via ancestry
            check, content-based `git cherry` detection, or PR-number scanning.
          items:
            type: string
        rebuild_triggered:
          type: boolean
          description: Whether this sync enqueued a rebuild job.
        rebuild_job_id:
          type: string
          format: uuid
          description: >-
            The enqueued rebuild job. Omitted entirely when no rebuild was
            enqueued -- it is never sent as null.
        force_push_detected:
          type: boolean
          description: >-
            Whether the new upstream HEAD is not a descendant of the previously
            stored one, indicating a history rewrite. Informational only -- the
            sync still proceeds.
        origin_fetched:
          type: boolean
          description: >-
            Always present. `true` when the fork (`origin`) was fetched in this
            sync (`PATCH_BRANCH_SOURCE=origin`), `false` otherwise.
        patches_synced:
          type: array
          description: >-
            Present only when `PATCH_BRANCH_SOURCE` is `origin` (empty `[]`
            when there are no candidates). Each element describes the
            per-branch outcome.
          items:
            $ref: "#/components/schemas/PatchSyncedElement"
        patches_diverged:
          type: array
          description: >-
            Present only when `PATCH_BRANCH_SOURCE` is `origin`. Branch names
            whose state is `diverged`. Always `[]` under the `replace` policy.
          items:
            type: string

    PatchSyncedElement:
      type: object
      description: Per-branch outcome of an origin-mode patch sync.
      required: [branch_name, action, state]
      properties:
        branch_name:
          type: string
        action:
          type: string
          enum: [none, created, fast_forwarded, replaced]
          description: What sync did to the local patch branch.
        state:
          type: string
          enum: [in_sync, diverged, missing_on_origin]
          description: Relationship between the local branch and the fork after the sync.
        local_sha:
          type: string
          description: Local tip after the refresh. Omitted when there is no local branch.
        origin_sha:
          type: string
          description: Fork tip SHA. Omitted when the fork has no such branch.
        replaced_sha:
          type: string
          description: The hub-side tip that was discarded. Present only for `replaced`.

    # -- Patches ---------------------------------------------------------------

    Patch:
      type: object
      description: A patch branch carried on top of the upstream base.
      required:
        - id
        - workspace_slug
        - branch_name
        - position
        - status
        - upstream_pr_url
        - description
        - deleted_at
        - added_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        workspace_slug:
          type: string
        branch_name:
          type: string
          description: The git branch backing this patch. Immutable after creation.
        position:
          type: integer
          minimum: 1
          description: 1-based application order; lower positions are applied first.
        status:
          $ref: "#/components/schemas/PatchStatus"
        conflict_files:
          type: array
          description: >-
            Conflicting file paths. Omitted entirely when the patch has no
            recorded conflicts.
          items:
            type: string
        upstream_pr_url:
          type: [string, "null"]
        description:
          type: [string, "null"]
        deleted_at:
          type: [string, "null"]
          format: date-time
          description: Soft-deletion timestamp; null for live patches.
        added_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        origin_sync_state:
          type: [string, "null"]
          enum: [in_sync, diverged, missing_on_origin, null]
          description: >-
            Relationship between the local patch branch and the fork after the
            last sync. Null in hub mode or when the patch has not been synced.
            Omitted when null.
        origin_sha:
          type: [string, "null"]
          description: >-
            SHA of the fork tip for this patch branch at the last sync. Null
            when the fork has no such branch or in hub mode. Omitted when null.
        origin_synced_at:
          type: [string, "null"]
          format: date-time
          description: >-
            Timestamp of the last origin sync for this patch. Null in hub mode.
            Omitted when null.

    AddPatchRequest:
      type: object
      required: [branch_name]
      properties:
        branch_name:
          type: string
          description: >-
            Must be non-empty, must differ from the workspace
            `integration_branch`, and must not already be registered.
        position:
          type: integer
          minimum: 1
          description: >-
            1-based insertion position. Values above `max(position) + 1` are
            clamped to an append. Omitted means append.
        upstream_pr_url:
          type: string
        description:
          type: string
        skip_branch_check:
          type: boolean
          default: false
          description: >-
            When true, skip all branch resolution: no ref lookup, no fetch,
            no local branch creation and no workspace lock is taken for this
            element.
        if_not_exists:
          type: boolean
          default: false
          description: >-
            When the branch is already registered, return `200` with the
            existing record instead of `409`.

    UpdatePatchRequest:
      type: object
      description: >-
        Partial update. `branch_name` is immutable and is silently ignored if
        present.
      properties:
        position:
          type: integer
          minimum: 1
          description: Must not exceed the workspace's total patch count.
        status:
          $ref: "#/components/schemas/PatchStatus"
        description:
          type: string
        upstream_pr_url:
          type: string

    ReorderPatchesRequest:
      type: object
      required: [patch_ids]
      properties:
        patch_ids:
          type: array
          description: >-
            Exactly the workspace's patch IDs in the desired order -- no
            missing, extra, or duplicated entries.
          items:
            type: string
            format: uuid

    # -- Rerere ----------------------------------------------------------------

    RerereListResponse:
      type: object
      required: [resolutions]
      properties:
        resolutions:
          type: array
          items:
            $ref: "#/components/schemas/RerereResolution"

    RerereResolution:
      type: object
      required: [id, path, recorded_at, resolved]
      properties:
        id:
          type: string
          description: rr-cache entry name (git's conflict hash); use it with DELETE.
        path:
          type: [string, "null"]
          description: >-
            File path of the conflict. Only known while the conflict is in
            progress (MERGE_RR), otherwise null.
        recorded_at:
          type: [string, "null"]
          format: date-time
          description: Derived from the modification time of the rr-cache entry.
        resolved:
          type: boolean
          description: True when a postimage (replayable resolution) is recorded.

    # -- Rebuilds --------------------------------------------------------------

    SubmitRebuildRequest:
      type: object
      description: >-
        Both fields are optional; each overrides the corresponding workspace
        variable for this run only.
      properties:
        strategy:
          type: string
          enum: [rebase, merge]
          description: >-
            `rebase` cherry-picks each unique commit; `merge` uses
            `git merge --no-ff`. Overrides `REBUILD_STRATEGY`.
        fail_mode:
          type: string
          enum: [fail_fast, continue]
          description: >-
            `fail_fast` aborts on the first unresolved conflict; `continue`
            marks the patch as `conflict`, resets to the pre-patch state, and
            proceeds. Overrides `REBUILD_FAIL_MODE`.

    RebuildJobEnqueued:
      type: object
      description: The durable job queue record returned when a rebuild is accepted.
      required: [id, type, key, group_key, status, payload]
      properties:
        id:
          type: string
          format: uuid
        type:
          const: rebuild
        key:
          type: string
          description: The deduplication key -- the workspace slug.
        group_key:
          type: string
          description: >-
            The serialization key, `<workspace-slug>:<integration-branch>`. At
            most one job per group runs at a time.
        status:
          $ref: "#/components/schemas/JobStatus"
        payload:
          $ref: "#/components/schemas/RebuildPayload"

    RebuildPayload:
      type: object
      properties:
        workspace_slug:
          type: string
        strategy:
          type: string
          enum: [rebase, merge]
        submitted_by:
          type: string
        integration_branch:
          type: string
        fail_mode:
          type: string
          enum: [fail_fast, continue]

    RebuildListResponse:
      type: object
      required: [jobs]
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/RebuildJob"

    RebuildJob:
      type: object
      description: |
        A rebuild of the integration branch. Fields carrying `omitempty` in the
        Go struct (`strategy`, `error`, `patch_results`,
        `integration_head_sha`, `previous_integration_head_sha`) are omitted
        when empty rather than serialised as null.
      required: [id, status, created_at, completed_at]
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/JobStatus"
        strategy:
          type: string
          enum: [rebase, merge]
        error:
          type: string
          description: Failure detail for failed jobs.
        created_at:
          type: string
          format: date-time
        completed_at:
          type: [string, "null"]
          format: date-time
          description: Null while the job is in a non-terminal state.
        patch_results:
          type: array
          description: >-
            Per-patch outcomes. Present for completed jobs, and for running jobs
            as intermediate progress that clients can poll.
          items:
            $ref: "#/components/schemas/RebuildPatchResult"
        integration_head_sha:
          type: string
          description: Integration branch HEAD after the rebuild.
        previous_integration_head_sha:
          type: string
          description: >-
            Integration branch HEAD before the rebuild. Empty on the first-ever
            rebuild.

    RebuildPatchResult:
      type: object
      required: [patch_id, branch_name, position, status, new_head_sha]
      properties:
        patch_id:
          type: string
          format: uuid
        branch_name:
          type: string
        position:
          type: integer
        status:
          type: string
          enum: [success, conflict, skipped]
        skipped_reason:
          type: string
          enum: [merged_upstream, disabled, deleted, branch_not_found]
          description: Present only when `status` is `skipped`.
        new_head_sha:
          oneOf:
            - $ref: "#/components/schemas/Sha"
            - type: "null"
          description: Null on conflict or skip.
        conflict_files:
          type: array
          description: Present only when `status` is `conflict`.
          items:
            type: string
        source_sha:
          $ref: "#/components/schemas/Sha"
          description: >-
            The commit `refs/heads/<branch_name>` resolved to when patch
            application began; the tip the rebuild applied. Omitted for patches
            that were not attempted (skipped by status or `branch_not_found`).
            Addressed as `patch_results[].source_sha` in rebuild job objects.

    RollbackResponse:
      type: object
      required: [rolled_back_to]
      properties:
        rolled_back_to:
          $ref: "#/components/schemas/Sha"

    RebuildPreviewResponse:
      type: object
      required: [patch_results]
      properties:
        patch_results:
          type: array
          items:
            $ref: "#/components/schemas/RebuildPreviewPatchResult"

    RebuildPreviewPatchResult:
      type: object
      required: [patch_id, branch_name, position, status, conflict_files]
      properties:
        patch_id:
          type: string
          format: uuid
        branch_name:
          type: string
        position:
          type: integer
        status:
          type: string
          enum: [would_succeed, would_conflict]
        tree_sha:
          type: string
          description: The resulting tree SHA. Omitted when the patch would conflict.
        conflict_files:
          type: array
          description: Empty when the patch would succeed.
          items:
            type: string

    PatchStatusResponse:
      type: object
      description: |
        Health dashboard for a carry-patch stack.

        Invariants: `summary.total_patches == len(patches)` and
        `summary.active + summary.merged_upstream + summary.conflict +
        summary.disabled == summary.total_patches`.
      required:
        - workspace_slug
        - workspace_mode
        - status
        - clone_status
        - sync_status
        - sync_mode
        - head_sha
        - git_url
        - upstream_url
        - upstream_head_sha
        - integration_branch
        - integration_head_sha
        - last_sync_at
        - last_rebuild
        - patches
        - summary
      properties:
        workspace_slug:
          type: string
        workspace_mode:
          const: carry_patch
        status:
          type: string
        clone_status:
          type: string
        clone_error:
          type: string
          description: Omitted when empty.
        sync_status:
          type: string
        sync_error:
          type: string
          description: Omitted when empty.
        sync_mode:
          type: string
        head_sha:
          type: string
          description: Empty when the workspace has not been cloned yet.
        git_url:
          type: string
        upstream_url:
          type: string
        upstream_head_sha:
          type: string
        integration_branch:
          type: string
        integration_head_sha:
          type: string
          description: >-
            Derived from the latest rebuild result; empty when no rebuild has
            been attempted.
        last_sync_at:
          type: [string, "null"]
          format: date-time
        last_rebuild:
          oneOf:
            - $ref: "#/components/schemas/PatchStatusRebuild"
            - type: "null"
          description: Null when no rebuild has been attempted.
        patches:
          type: array
          description: All non-deleted patches, ordered by position.
          items:
            $ref: "#/components/schemas/PatchStatusEntry"
        summary:
          $ref: "#/components/schemas/PatchStatusSummary"

    PatchStatusRebuild:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"

    PatchStatusEntry:
      type: object
      required: [id, branch_name, position, status, last_rebuild_result]
      properties:
        id:
          type: string
        branch_name:
          type: string
        position:
          type: integer
        status:
          $ref: "#/components/schemas/PatchStatus"
        last_rebuild_result:
          type: [string, "null"]
          enum: [success, conflict, skipped, null]
          description: Null when no rebuild has been attempted.
        conflict_files:
          type: array
          description: Present only when `last_rebuild_result` is `conflict`.
          items:
            type: string
        origin_sync_state:
          type: [string, "null"]
          enum: [in_sync, diverged, missing_on_origin, null]
          description: >-
            Relationship between the local patch branch and the fork after the
            last sync. Null in hub mode. Omitted when null.
        origin_sha:
          type: [string, "null"]
          description: >-
            SHA of the fork tip at the last sync. Null when the fork has no
            such branch or in hub mode. Omitted when null.
        origin_synced_at:
          type: [string, "null"]
          format: date-time
          description: >-
            Timestamp of the last origin sync. Null in hub mode. Omitted when
            null.

    PatchStatusSummary:
      type: object
      required:
        - total_patches
        - active
        - merged_upstream
        - conflict
        - disabled
        - total_rerere_resolutions
        - patches_diverged
        - patches_missing_on_origin
      properties:
        total_patches:
          type: integer
        active:
          type: integer
        merged_upstream:
          type: integer
        conflict:
          type: integer
        disabled:
          type: integer
        total_rerere_resolutions:
          type: integer
          description: Reported as 0 when the rr-cache is inaccessible.
        patches_diverged:
          type: integer
          description: >-
            Count of patches whose origin_sync_state is diverged. Always
            present; 0 in hub mode.
        patches_missing_on_origin:
          type: integer
          description: >-
            Count of patches whose origin_sync_state is missing_on_origin.
            Always present; 0 in hub mode.

    # -- Merges ----------------------------------------------------------------

    SubmitMergeRequest:
      type: object
      required: [target_branch, source_ref]
      properties:
        target_branch:
          type: string
          description: The branch being merged into.
        source_ref:
          type: string
          description: The branch being merged from.

    MergeJob:
      type: object
      required:
        - id
        - workspace_slug
        - target_branch
        - source_ref
        - status
        - base_sha
        - merged_sha
        - conflict_files
        - check_output
        - error
        - retry_count
        - submitted_by
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        workspace_slug:
          type: string
        target_branch:
          type: string
        source_ref:
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        base_sha:
          oneOf:
            - $ref: "#/components/schemas/Sha"
            - type: "null"
          description: Target HEAD before the merge; null until the job completes.
        merged_sha:
          oneOf:
            - $ref: "#/components/schemas/Sha"
            - type: "null"
          description: Target HEAD after the merge; null until the job completes.
        conflict_files:
          type: array
          items:
            type: string
        check_output:
          type: [string, "null"]
          description: Output of the `CHECK_COMMAND` if one ran.
        error:
          type: [string, "null"]
        retry_count:
          type: integer
        submitted_by:
          type: string
          description: The authenticated identity that submitted the job.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    BatchRebaseRequest:
      type: object
      required: [target_ref, branches]
      properties:
        target_ref:
          type: string
        branches:
          type: array
          minItems: 1
          items:
            type: string

    BatchRebaseResponse:
      type: object
      required: [results]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/RebaseResult"

    RebaseResult:
      type: object
      required: [branch, status]
      properties:
        branch:
          type: string
        status:
          type: string
          enum: [ok, conflict, error]
        new_head:
          allOf:
            - $ref: "#/components/schemas/Sha"
          description: Omitted on conflict or error.
        conflict_files:
          type: array
          description: Omitted on success.
          items:
            type: string

    CancelledAck:
      type: object
      properties:
        status:
          const: cancelled

    # -- Secrets and variables -------------------------------------------------

    CreateEntriesRequest:
      type: object
      required: [entries]
      properties:
        entries:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/EntryInput"

    EntryInput:
      type: object
      required: [key, value]
      properties:
        key:
          $ref: "#/components/schemas/EntryKeyName"
        value:
          type: string
          description: At most 256 KB (262144 bytes) once encoded.

    UpdateValueRequest:
      type: object
      required: [value]
      properties:
        value:
          type: string

    SecretEntry:
      type: object
      description: A secret. The value is never returned by the API.
      required: [key, created_at, updated_at]
      properties:
        key:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      additionalProperties: false

    VariableEntry:
      type: object
      required: [key, value, created_at, updated_at]
      properties:
        key:
          type: string
        value:
          type: string
          description: Stored base64-encoded internally and returned decoded.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ResolvedVariableEntry:
      type: object
      required: [key, value, origin, created_at, updated_at]
      properties:
        key:
          type: string
        value:
          type: string
        origin:
          type: string
          enum: [user, org, workspace]
          description: Which tier supplied the winning value.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    WorkspaceVariables:
      type: object
      description: |
        Reference for the workspace variable keys the hub interprets. This
        schema is documentation only -- it is not a request or response body.
        Set these through `POST /api/v1/workspaces/{slug}/vars`.
      properties:
        REBUILD_STRATEGY:
          type: string
          enum: [rebase, merge]
          default: rebase
          description: >-
            Strategy used to apply patches during a rebuild. Overridable
            per-rebuild via the `strategy` request field.
        REBUILD_FAIL_MODE:
          type: string
          enum: [fail_fast, continue]
          default: fail_fast
          description: >-
            Whether a rebuild aborts on the first conflict or skips the
            conflicting patch and continues. Overridable per-rebuild via the
            `fail_mode` request field.
        AUTO_REBUILD_AFTER_SYNC:
          type: string
          enum: ["true", "false"]
          default: "true"
          description: >-
            When not `"false"`, a carry-patch sync that observes upstream
            advancement enqueues a rebuild.
        AUTO_REBUILD_AFTER_PUSH:
          type: string
          enum: ["true", "false"]
          default: "true"
          description: >-
            When not `"false"`, a push to a registered patch branch enqueues a
            rebuild.
        PUSH_PATCHES_TO_ORIGIN:
          type: string
          enum: ["true"]
          description: >-
            Enables forwarding or mirroring of hub pushes to registered patch
            branches. Only the exact string `"true"` enables it. In `origin`
            mode, enables forwarding to the fork before the hub writes its ref;
            when disabled, the push is rejected. In `hub` mode, enables
            best-effort mirroring (force-push) to the fork after the push is
            accepted.
        SQUASH_MERGE_DETECTION:
          type: string
          enum: [ancestry_only, content_based, both]
          default: both
          description: >-
            Which strategies detect upstream merges during a carry-patch sync.
            `ancestry_only` uses `git merge-base --is-ancestor`;
            `content_based` uses `git cherry` plus PR-number scanning; `both`
            uses all of them and treats either signal as sufficient.
        CHECK_COMMAND:
          type: string
          description: >-
            Shell command run through `sh -c` after a merge rebase. A non-zero
            exit rolls the rebase back.

    # -- Sessions --------------------------------------------------------------

    CreateSessionRequest:
      type: object
      required: [workspace_slug]
      properties:
        id:
          type: string
          description: Client-provided identifier; generated when omitted. Makes the call idempotent.
        workspace_slug:
          type: string
        run_id:
          type: string
          description: Groups sessions belonging to the same run.
        node_id:
          type: string
          description: Task-graph node identifier.
        archetype:
          type: string
          description: Agent archetype label.
        model:
          type: string
        metadata:
          description: Arbitrary JSON metadata.

    CompleteSessionRequest:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [completed, failed, timeout]
          description: "`terminated` is server-only and is rejected here."
        error_message:
          type: string
        duration_ms:
          type: [integer, "null"]
          format: int64
        cache_creation_input_tokens:
          type: integer
          format: int64

    ReportUsageRequest:
      type: object
      required: [model]
      properties:
        id:
          type: string
          description: Client-provided identifier; generated when omitted.
        model:
          type: string
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cache_read_tokens:
          type: integer
          format: int64
          minimum: 0

    Session:
      type: object
      required: [id, workspace_slug, status, credential_id, credential_type, started_at]
      properties:
        id:
          type: string
        workspace_slug:
          type: string
        run_id:
          type: string
        node_id:
          type: string
        archetype:
          type: string
        model:
          type: string
        status:
          $ref: "#/components/schemas/SessionStatus"
        credential_id:
          type: string
          description: Identifier of the credential that opened the session.
        credential_type:
          type: string
          enum: [admin_token, api_key, pat]
        error_message:
          type: string
        started_at:
          type: string
          format: date-time
        ended_at:
          type: [string, "null"]
          format: date-time
        duration_ms:
          type: [integer, "null"]
          format: int64
        cache_creation_input_tokens:
          type: integer
          format: int64
        metadata: {}
        token_summary:
          $ref: "#/components/schemas/TokenSummary"

    TokenSummary:
      type: object
      required: [total_input_tokens, total_output_tokens, total_cache_read_tokens, models_used]
      properties:
        total_input_tokens:
          type: integer
          format: int64
        total_output_tokens:
          type: integer
          format: int64
        total_cache_read_tokens:
          type: integer
          format: int64
        models_used:
          type: array
          items:
            type: string

    TokenUsage:
      type: object
      required:
        - id
        - session_id
        - workspace_slug
        - model
        - input_tokens
        - output_tokens
        - cache_read_tokens
        - reported_at
      properties:
        id:
          type: string
        session_id:
          type: string
        workspace_slug:
          type: string
        model:
          type: string
        input_tokens:
          type: integer
          format: int64
        output_tokens:
          type: integer
          format: int64
        cache_read_tokens:
          type: integer
          format: int64
        reported_at:
          type: string
          format: date-time

    SessionListResponse:
      type: object
      required: [sessions, next_cursor, has_more]
      properties:
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/Session"
        next_cursor:
          type: [string, "null"]
        has_more:
          type: boolean

    UsageListResponse:
      type: object
      required: [session_id, records, totals, next_cursor, has_more]
      properties:
        session_id:
          type: string
        records:
          type: array
          items:
            $ref: "#/components/schemas/TokenUsage"
        totals:
          allOf:
            - $ref: "#/components/schemas/TokenSummary"
          description: Aggregates every record for the session, not just this page.
        next_cursor:
          type: [string, "null"]
        has_more:
          type: boolean

    CostResponse:
      type: object
      required: [workspace, period, totals, breakdown]
      properties:
        workspace:
          type: string
        period:
          type: object
          required: [since, until]
          properties:
            since:
              type: string
              format: date-time
            until:
              type: string
              format: date-time
        totals:
          type: object
          required: [input_tokens, output_tokens, cache_read_tokens, sessions]
          properties:
            input_tokens:
              type: integer
              format: int64
            output_tokens:
              type: integer
              format: int64
            cache_read_tokens:
              type: integer
              format: int64
            sessions:
              type: integer
              format: int64
        breakdown:
          type: array
          items:
            $ref: "#/components/schemas/CostBreakdownEntry"

    CostBreakdownEntry:
      type: object
      description: >-
        Exactly one of `date`, `session_id`, or `model` is populated, matching
        the requested `group_by`.
      required: [input_tokens, output_tokens, cache_read_tokens, sessions]
      properties:
        date:
          type: string
          description: Present when `group_by=day`.
        session_id:
          type: string
          description: Present when `group_by=session`.
        model:
          type: string
          description: Present when `group_by=model`.
        input_tokens:
          type: integer
          format: int64
        output_tokens:
          type: integer
          format: int64
        cache_read_tokens:
          type: integer
          format: int64
        sessions:
          type: integer
          format: int64

    # -- Audit ingestion -------------------------------------------------------

    PostEventRequest:
      type: object
      required: [event_type]
      properties:
        id:
          type: string
          description: Client-provided identifier; generated when omitted. Makes ingestion idempotent.
        run_id:
          type: string
          description: >-
            When present it must match the `run_id` in the URL, otherwise the
            request is rejected with `400`.
        event_type:
          type: string
        severity:
          allOf:
            - $ref: "#/components/schemas/Severity"
          description: Defaults to a per-event-type value chosen by the server.
        node_id:
          type: string
        session_id:
          type: string
        timestamp:
          type: string
          format: date-time
          description: Defaults to the current UTC time.
        payload:
          type: object
          additionalProperties: true

    PostEventResponse:
      type: object
      required: [id, run_id, event_type, severity, created_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        event_type: { type: string }
        severity: { type: string }
        created_at: { type: string, format: date-time }

    PostSessionOutcomeRequest:
      type: object
      required: [session_id, status]
      properties:
        id: { type: string }
        run_id: { type: string }
        session_id: { type: string }
        node_id: { type: string }
        status: { type: string }
        timestamp: { type: string, format: date-time }
        duration_ms:
          type: integer
          format: int64
          minimum: 0
        token_usage:
          type: object
          additionalProperties: true

    PostSessionOutcomeResponse:
      type: object
      required: [id, run_id, node_id, status, created_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        node_id: { type: string }
        status: { type: string }
        created_at: { type: string, format: date-time }

    PostToolCallRequest:
      type: object
      required: [tool_name]
      properties:
        id: { type: string }
        run_id: { type: string }
        tool_name: { type: string }
        node_id: { type: string }
        session_id: { type: string }
        timestamp: { type: string, format: date-time }
        duration_ms: { type: integer, format: int64 }
        input:
          type: object
          additionalProperties: true
        output:
          type: object
          additionalProperties: true

    PostToolCallResponse:
      type: object
      required: [id, run_id, tool_name, called_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        tool_name: { type: string }
        called_at: { type: string, format: date-time }

    PostToolErrorRequest:
      type: object
      required: [tool_name, error_msg]
      properties:
        id: { type: string }
        run_id: { type: string }
        tool_name: { type: string }
        node_id: { type: string }
        session_id: { type: string }
        error_code: { type: string }
        error_msg: { type: string }
        timestamp: { type: string, format: date-time }

    PostToolErrorResponse:
      type: object
      required: [id, run_id, tool_name, failed_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        tool_name: { type: string }
        failed_at: { type: string, format: date-time }

    PostTraceRequest:
      type: object
      required: [event_type]
      properties:
        id: { type: string }
        run_id: { type: string }
        event_type:
          type: string
          enum: [session.init, assistant.message, tool.use, tool.error, session.result]
        node_id: { type: string }
        session_id: { type: string }
        sequence: { type: integer }
        timestamp: { type: string, format: date-time }
        data:
          type: object
          additionalProperties: true

    PostTraceResponse:
      type: object
      required: [id, run_id, event_type, timestamp]
      properties:
        id: { type: string }
        run_id: { type: string }
        event_type: { type: string }
        timestamp: { type: string, format: date-time }

    PostPostmortemRequest:
      type: object
      required: [run_status, started_at, completed_at, task_summary, cost_summary]
      properties:
        schema_version:
          type: integer
          const: 1
          description: Rejected with `422` when present and not 1.
        run_status:
          type: string
          enum: [stalled, block_limit, cost_limit, session_limit]
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        task_summary:
          type: object
          description: Must contain a `total` field.
          required: [total]
          additionalProperties: true
          properties:
            total: { type: integer }
        cost_summary:
          type: object
          description: Aggregated token and cost totals.
          additionalProperties: true
        blocked_tasks:
          type: array
          items:
            type: object
            properties:
              node_id: { type: string }
              reason: { type: string }
            additionalProperties: true
        session_history:
          type: array
          description: Opaque JSON array, stored as-is.
          items: {}

    PostPostmortemResponse:
      type: object
      required: [run_id, run_status, created_at]
      properties:
        run_id: { type: string }
        run_status: { type: string }
        created_at: { type: string, format: date-time }

    Postmortem:
      type: object
      required:
        - run_id
        - workspace
        - schema_version
        - run_status
        - started_at
        - completed_at
        - task_summary
        - cost_summary
        - blocked_tasks
        - session_history
        - ingested_at
      properties:
        run_id: { type: string }
        workspace: { type: string }
        schema_version: { type: integer }
        run_status: { type: string }
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        task_summary: {}
        cost_summary: {}
        blocked_tasks: {}
        session_history: {}
        ingested_at: { type: string, format: date-time }

    BatchIngestResponse:
      type: object
      required: [accepted, duplicates, errors]
      properties:
        accepted:
          type: integer
          description: Rows written.
        duplicates:
          type: integer
          description: Rows skipped because the identifier already existed.
        errors:
          type: array
          items:
            type: object
            required: [index, message]
            properties:
              index:
                type: integer
                description: Zero-based position of the failing item in the request array.
              id: { type: string }
              message: { type: string }

    # -- Audit query -----------------------------------------------------------

    AgentAuditEvent:
      type: object
      description: An agent-submitted audit event as returned by the per-run query.
      required: [id, run_id, workspace, event_type, severity, node_id, session_id, timestamp, ingested_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        workspace: { type: string }
        event_type: { type: string }
        severity: { type: string }
        node_id: { type: string }
        session_id: { type: string }
        timestamp: { type: string, format: date-time }
        payload:
          description: >-
            The stored payload, decoded from JSON. Falls back to the raw string
            when it cannot be parsed.
        ingested_at: { type: string, format: date-time }

    AgentSessionOutcome:
      type: object
      required: [id, run_id, workspace, session_id, node_id, status, timestamp, duration_ms, ingested_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        workspace: { type: string }
        session_id: { type: string }
        node_id: { type: string }
        status: { type: string }
        timestamp: { type: string, format: date-time }
        duration_ms: { type: integer }
        token_usage: {}
        ingested_at: { type: string, format: date-time }

    AgentToolCall:
      type: object
      required: [id, run_id, workspace, tool_name, node_id, session_id, timestamp, duration_ms, ingested_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        workspace: { type: string }
        tool_name: { type: string }
        node_id: { type: string }
        session_id: { type: string }
        timestamp: { type: string, format: date-time }
        duration_ms: { type: integer }
        input: {}
        output: {}
        ingested_at: { type: string, format: date-time }

    AgentToolError:
      type: object
      required: [id, run_id, workspace, tool_name, node_id, session_id, error_code, error_msg, timestamp, ingested_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        workspace: { type: string }
        tool_name: { type: string }
        node_id: { type: string }
        session_id: { type: string }
        error_code: { type: string }
        error_msg: { type: string }
        timestamp: { type: string, format: date-time }
        ingested_at: { type: string, format: date-time }

    AgentTrace:
      type: object
      required: [id, run_id, workspace, event_type, node_id, session_id, sequence, timestamp, ingested_at]
      properties:
        id: { type: string }
        run_id: { type: string }
        workspace: { type: string }
        event_type: { type: string }
        node_id: { type: string }
        session_id: { type: string }
        sequence: { type: integer }
        timestamp: { type: string, format: date-time }
        data: {}
        ingested_at: { type: string, format: date-time }

    CursorPage:
      type: object
      description: Fields shared by every cursor-paginated audit response.
      required: [next_cursor, has_more]
      properties:
        next_cursor:
          type: [string, "null"]
          description: Opaque token for the next page, or null when this is the last one.
        has_more:
          type: boolean

    RunEventListResponse:
      allOf:
        - $ref: "#/components/schemas/CursorPage"
        - type: object
          required: [events]
          properties:
            events:
              type: array
              items:
                $ref: "#/components/schemas/AgentAuditEvent"

    RunOutcomeListResponse:
      allOf:
        - $ref: "#/components/schemas/CursorPage"
        - type: object
          required: [outcomes]
          properties:
            outcomes:
              type: array
              items:
                $ref: "#/components/schemas/AgentSessionOutcome"

    RunToolCallListResponse:
      allOf:
        - $ref: "#/components/schemas/CursorPage"
        - type: object
          required: [calls]
          properties:
            calls:
              type: array
              items:
                $ref: "#/components/schemas/AgentToolCall"

    RunToolErrorListResponse:
      allOf:
        - $ref: "#/components/schemas/CursorPage"
        - type: object
          required: [errors]
          properties:
            errors:
              type: array
              items:
                $ref: "#/components/schemas/AgentToolError"

    RunTraceListResponse:
      allOf:
        - $ref: "#/components/schemas/CursorPage"
        - type: object
          required: [traces]
          properties:
            traces:
              type: array
              items:
                $ref: "#/components/schemas/AgentTrace"

    UnifiedAuditQueryResponse:
      allOf:
        - $ref: "#/components/schemas/CursorPage"
        - type: object
          required: [events]
          properties:
            events:
              type: array
              description: Merged hub and agent events, newest first.
              items:
                $ref: "#/components/schemas/UnifiedAuditEvent"

    UnifiedAuditEvent:
      type: object
      description: >-
        A hub or agent audit event. The hub-only fields (`actor_id`,
        `actor_type`, `resource_type`, `resource_id`, `action`) are null on
        agent events, and the agent-only fields (`run_id`, `node_id`,
        `session_id`, `archetype`) are null on hub events.
      required:
        - id
        - event_type
        - source
        - timestamp
        - severity
        - workspace
        - actor_id
        - actor_type
        - resource_type
        - resource_id
        - action
        - run_id
        - node_id
        - session_id
        - archetype
      properties:
        id:
          type: string
        event_type:
          type: string
          description: Dot-notation type, for example `hub.workspace.create`.
        source:
          type: string
          enum: [hub, agent]
        timestamp:
          type: string
          format: date-time
        severity:
          type: string
        workspace:
          type: string
        actor_id:
          type: [string, "null"]
        actor_type:
          type: [string, "null"]
        resource_type:
          type: [string, "null"]
        resource_id:
          type: [string, "null"]
        action:
          type: [string, "null"]
        run_id:
          type: [string, "null"]
        node_id:
          type: [string, "null"]
        session_id:
          type: [string, "null"]
        archetype:
          type: [string, "null"]

    TranscriptResponse:
      type: object
      required: [run_id, node_id, messages]
      properties:
        run_id:
          type: string
        node_id:
          type: string
        messages:
          type: array
          items:
            $ref: "#/components/schemas/TranscriptMessage"

    TranscriptMessage:
      type: object
      required: [role, content, tool_name, timestamp]
      properties:
        role:
          type: string
          enum: [system, assistant, tool_use, tool_error]
        content:
          type: string
        tool_name:
          type: [string, "null"]
        timestamp:
          type: string
          format: date-time

    # -- Identity (apikit) -----------------------------------------------------

    User:
      type: object
      description: A user account.
      required:
        - id
        - username
        - email
        - full_name
        - role
        - status
        - provider
        - provider_id
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        email:
          type: string
          format: email
        full_name:
          type: string
        role:
          type: string
          enum: [user, admin]
          description: >-
            An `admin` role grants access to the administration endpoints when
            the credential is an API key. It confers no cross-tenant workspace
            or git access -- those check for an admin token directly.
        status:
          type: string
          description: >-
            `blocked` disables every API key the user owns at authentication
            time, without revoking them.
        provider:
          type: string
          description: The OAuth provider that authenticated this identity.
          examples: [github]
        provider_id:
          type: string
          description: The user's identifier at the OAuth provider.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required: [username, email, provider, provider_id]
      properties:
        username:
          type: string
        email:
          type: string
          format: email
        provider:
          type: string
        provider_id:
          type: string

    UpdateUserRequest:
      type: object
      description: >-
        `full_name` is the only mutable profile field. It is required: a
        missing or null value is rejected with `400`.
      required: [full_name]
      properties:
        full_name:
          type: string

    Organization:
      type: object
      required: [id, name, slug, url, status, created_at, updated_at]
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        url:
          type: string
        owner_id:
          type: [string, "null"]
          format: uuid
          description: Omitted when the organization has no owner.
        status:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    OrgMember:
      type: object
      required: [org_id, user_id, username, email, role, created_at]
      properties:
        org_id:
          type: string
        user_id:
          type: string
          format: uuid
        username:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
        created_at:
          type: string
          format: date-time

    CreateOrgRequest:
      type: object
      required: [name, slug]
      properties:
        name:
          type: string
        slug:
          type: string
          description: Validated against the server's slug format.
        url:
          type: string
        owner_id:
          type: string
          format: uuid

    UpdateOrgRequest:
      type: object
      description: At least one field must be supplied.
      minProperties: 1
      properties:
        name:
          type: string
          description: Rejected when set to an empty string.
        url:
          type: string

    ApiKeyMeta:
      type: object
      description: >-
        API key metadata. The secret hash, the configured lifetime in days, and
        the plaintext secret are never exposed.
      required: [key_id, created_at, expires_at, revoked_at]
      properties:
        key_id:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: [string, "null"]
          format: date-time
          description: Null for a non-expiring key.
        revoked_at:
          type: [string, "null"]
          format: date-time

    ApiKeyMetaWithOwner:
      allOf:
        - $ref: "#/components/schemas/ApiKeyMeta"
        - type: object
          required: [user_id]
          properties:
            user_id:
              type: string
              format: uuid

    ApiKeyFull:
      type: object
      description: >-
        An API key including its plaintext value. Returned only by the OAuth
        callback and the refresh endpoint; the server persists only the
        SHA-256 hash.
      required: [key, key_id, expires_at]
      properties:
        key:
          type: string
          format: password
          description: The full `af_<key_id>_<secret>` value.
        key_id:
          type: string
        expires_at:
          type: [string, "null"]
          format: date-time

    PersonalAccessToken:
      type: object
      description: PAT metadata, never including the plaintext secret.
      required: [token_id, name, permissions, expires_at, created_at, revoked_at]
      properties:
        token_id:
          type: string
        name:
          type: string
          maxLength: 255
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/PermissionScope"
        expires_at:
          type: [string, "null"]
          format: date-time
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: [string, "null"]
          format: date-time

    PersonalAccessTokenWithOwner:
      allOf:
        - $ref: "#/components/schemas/PersonalAccessToken"
        - type: object
          required: [user_id]
          properties:
            user_id:
              type: string
              format: uuid

    PersonalAccessTokenWithSecret:
      type: object
      description: A newly created PAT, including its one-time plaintext value.
      required: [token_id, name, token, permissions, expires_at, created_at]
      properties:
        token_id:
          type: string
        name:
          type: string
        token:
          type: string
          format: password
          description: >-
            The full `af_pat_<token_id>_<secret>` value. Returned once at
            creation and never again.
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/PermissionScope"
        expires_at:
          type: [string, "null"]
          format: date-time
        created_at:
          type: string
          format: date-time

    CreateTokenRequest:
      type: object
      required: [name, permissions]
      properties:
        name:
          type: string
          maxLength: 255
        permissions:
          type: array
          minItems: 1
          description: >-
            Every entry must be a registered scope. A PAT creating another PAT
            may only grant permissions it already holds.
          items:
            $ref: "#/components/schemas/PermissionScope"
        expires:
          type: integer
          enum: [0, 30, 60, 90]
          description: Token lifetime in days. `0` means no expiry.

    PermissionsRequest:
      type: object
      description: >-
        On `PUT`, an explicit empty array clears every permission and
        auto-revokes the token. On `PATCH` and `DELETE` an empty array is an
        error. An absent or null `permissions` field is always an error.
      required: [permissions]
      properties:
        permissions:
          type: array
          items:
            $ref: "#/components/schemas/PermissionScope"

    OAuthProvider:
      type: object
      required: [name, authorize_url]
      properties:
        name:
          type: string
          examples: [github]
        authorize_url:
          type: string
          description: The URL to send the user to in order to begin the OAuth flow.

    OAuthCallbackRequest:
      type: object
      required: [provider, code]
      properties:
        provider:
          type: string
          description: The provider name, as listed by `GET /api/v1/auth/providers`.
          examples: [github]
        code:
          type: string
          description: The authorization code returned by the OAuth provider.
        redirect_uri:
          type: string
          description: Validated against the provider's redirect allowlist.
        expires:
          type: [integer, "null"]
          enum: [0, 30, 60, 90, null]
          default: 90
          description: Requested API key lifetime in days. `0` means no expiry.

    OAuthCallbackResponse:
      type: object
      required: [user, api_key]
      properties:
        user:
          type: object
          required: [id, username, email, full_name, status, role, provider, provider_id, created_at, updated_at]
          properties:
            id: { type: string, format: uuid }
            username: { type: string }
            email: { type: string, format: email }
            full_name: { type: [string, "null"] }
            status: { type: string }
            role: { type: string }
            provider: { type: string }
            provider_id: { type: string }
            created_at: { type: string, format: date-time }
            updated_at: { type: string, format: date-time }
        api_key:
          $ref: "#/components/schemas/ApiKeyFull"

    VersionResponse:
      type: object
      required: [go_version, build_time, commit, mount_point]
      properties:
        go_version:
          type: string
          description: The server version stamped at build time.
        build_time:
          type: string
        commit:
          type: string
        mount_point:
          type: string
          description: The prefix the API group is mounted at.
          default: /api/v1

    PermissionScope:
      type: string
      description: |
        A `resource:action` permission scope. Both halves match `^[a-z0-9_]+$`.
        The registry holds 33 scopes: 8 built into apikit and 25 registered by
        hub modules at startup. PAT creation rejects unknown scopes with `400`.

        Implications: `workspaces:create` and `workspaces:write` imply
        `workspaces:read` for workspace list and get only -- the rerere and
        patch-status handlers test for the literal `workspaces:read` string.
        `patches:write` implies `patches:read`; `git:write` implies `git:read`;
        `secrets:manage` implies `secrets:list`, `secrets:write`, and
        `secrets:delete`; `vars:manage` implies `vars:read`, `vars:write`, and
        `vars:delete`; and `vars:write` implies `vars:read`.
        `workspaces:delete` and `workspaces:sync` imply nothing.
      pattern: "^[a-z0-9_]+:[a-z0-9_]+$"
      enum:
        - audit:read
        - audit:write
        - git:read
        - git:write
        - keys:manage
        - keys:read
        - merges:read
        - merges:write
        - orgs:read
        - orgs:write
        - patches:read
        - patches:write
        - rebuilds:read
        - rebuilds:write
        - secrets:delete
        - secrets:list
        - secrets:manage
        - secrets:write
        - sessions:read
        - sessions:write
        - tokens:manage
        - tokens:read
        - tokens:write
        - users:read
        - vars:delete
        - vars:manage
        - vars:read
        - vars:write
        - workspaces:create
        - workspaces:delete
        - workspaces:read
        - workspaces:sync
        - workspaces:write