Bernstein Governance API

openapi: 3.2.0
info:
  title: Bernstein Task Server Governance API
  description: 'Bernstein REST API - the open-source governance layer for AI agents, one git worktree per task.


    ## Authentication


    Authentication is ENABLED by default. Include a Bearer token in all requests:


    ```

    Authorization: Bearer

    ```


    To run without auth (development only), set `BERNSTEIN_AUTH_DISABLED=1` - this logs a loud warning and passes every request through.


    Public endpoints (no auth required): `/health`, `/health/ready`, `/health/live`, `/ready`, `/alive`, `/.well-known/agent.json`, `/docs`, `/openapi.json`, and the auth-flow endpoints (`/auth/login`, `/auth/oidc/callback`, etc.).


    Webhook and hook endpoints (`/webhook`, `/webhooks/*`, `/hooks/{session_id}`) authenticate via HMAC-SHA256 signatures - they do NOT accept Bearer tokens.


    ## Base URL


    Default: `http://127.0.0.1:8052`. Override with env vars `BERNSTEIN_HOST` and `BERNSTEIN_PORT`.


    ## Error Format


    All errors return JSON with a `detail` field:


    ```json

    {"detail": "Task not found: task-xyz"}

    ```


    | Status | Meaning |

    |--------|---------|

    | 400 | Bad request (validation error) |

    | 401 | Unauthorized (missing/invalid token) |

    | 403 | Forbidden (IP not in allowlist) |

    | 404 | Resource not found |

    | 409 | Conflict (task already in terminal state) |

    | 429 | Rate limited - respect the `Retry-After` header |

    | 500 | Internal server error |'
  version: 3.22.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Alex Chernysh
    url: https://github.com/sipyourdrink-ltd/bernstein
servers:
- url: http://{host}:{port}
  description: Task server started by the Bernstein CLI on the operator's own machine. There is no hosted instance; substitute the host and port of your install.
  variables:
    host:
      default: 127.0.0.1
      description: Interface the task server binds to. Loopback by default.
    port:
      default: '8052'
      description: Task server port. Override with BERNSTEIN_PORT.
tags:
- name: Governance
paths:
  /governance/coverage:
    get:
      tags:
      - Governance
      summary: Governance Coverage
      description: Return the canonical coverage document for ``?run_id=``.
      operationId: governance_coverage_governance_coverage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /governance/verify-receipt:
    post:
      tags:
      - Governance
      summary: Verify Receipt
      description: 'Verify the posted receipt file and return the verdict document.


        The request body is the receipt verbatim -- whatever the operator dropped,

        of whatever content type. Nothing under ``.sdd`` and no key material is

        read: the verifier works from the file''s own bytes, so this endpoint

        answers about the upload and not about the installation serving it.


        The status is always 200 for a request that carried a body. A tampered

        receipt, a file that is not a receipt, and an empty drop are all verdicts

        about the evidence rather than failed requests, and each is the answer an

        operator dropped the file to get.


        No key can be pinned through this endpoint, so the pass it reports is

        always the integrity-only tier and always carries the caveat saying so.

        A key arriving in the same request as the receipt is not an out-of-band

        anchor -- it is the same channel, and treating it as one would report

        provenance on the strength of the upload rather than of any evidence.'
      operationId: verify_receipt_governance_verify_receipt_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/v1/governance/coverage:
    get:
      tags:
      - Governance
      summary: Governance Coverage
      description: Return the canonical coverage document for ``?run_id=``.
      operationId: governance_coverage_api_v1_governance_coverage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/v1/governance/verify-receipt:
    post:
      tags:
      - Governance
      summary: Verify Receipt
      description: 'Verify the posted receipt file and return the verdict document.


        The request body is the receipt verbatim -- whatever the operator dropped,

        of whatever content type. Nothing under ``.sdd`` and no key material is

        read: the verifier works from the file''s own bytes, so this endpoint

        answers about the upload and not about the installation serving it.


        The status is always 200 for a request that carried a body. A tampered

        receipt, a file that is not a receipt, and an empty drop are all verdicts

        about the evidence rather than failed requests, and each is the answer an

        operator dropped the file to get.


        No key can be pinned through this endpoint, so the pass it reports is

        always the integrity-only tier and always carries the caveat saying so.

        A key arriving in the same request as the receipt is not an out-of-band

        anchor -- it is the same channel, and treating it as one would report

        provenance on the strength of the upload rather than of any evidence.'
      operationId: verify_receipt_api_v1_governance_verify_receipt_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}