Annsa Service API

openapi: 3.2.0
info:
  title: Annsa Service API
  version: '2026-08-22'
  summary: Send customer feedback and call transcripts into Annsa, and reach its priorities and specs over MCP.
  description: 'Annsa is the source of direction for your agents. Choose what to build from your customers, roadmap, ideas and agent findings, then direct every agent and learn as you go.


    This document describes only what is public and callable today. Endpoints used by the Annsa web app on a user''s own session are deliberately absent.


    ## Rate limits


    Limits are abuse ceilings, not metering — plan quotas are separate and are enforced on your account, not on the connection. `POST /feedback` and `POST /surface/submit` allow 5000 requests an hour; `POST /transcripts/upload` allows 500, because each call does real work. `POST /mcp` and `GET /health` carry no limit of their own.


    A window is counted per authenticated caller, falling back to the client IP when there is no credential. Limited endpoints report where you stand in it on every response — `RateLimit`, plus the discrete `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` — so you never have to discover a limit by being refused. `RateLimit-Reset` is delta-seconds, not a timestamp. A 429 adds `Retry-After`. The full policy is at https://annsa.ai/api-policy.


    ## Which credential to use


    There are two separate authentication systems, and they are not interchangeable:


    - **`sessionBearer`** — a Supabase session token belonging to a signed-in user. Required by `POST /feedback` and `POST /transcripts/upload`. A survey key sent here returns 401.

    - **`surveyKey`** — the key from Settings → Integrations → Survey. It authenticates `POST /surface/submit` **only**, and travels in the JSON body as `api_key`, not in a header — so it is described on the `WidgetSubmission` schema rather than as a security scheme, because OpenAPI has no way to express a body-field credential. This key is embedded in public web pages by design, so its reach is deliberately narrow.


    For reading priorities, specs and search, use the MCP server rather than REST. It is OAuth 2.0 with PKCE and scoped `read`/`write`, and it is the surface built for agents. See `POST /mcp`.


    ## Errors


    Every error response is `application/json` in the shape `{"detail": "..."}` (the `Error` schema). `detail` is a human-readable string; it is not a stable machine code, so branch on the HTTP status rather than on the text.


    ## Versioning


    This API is unversioned in the path. The `info.version` above is the date this document was published, and this document is the contract. Additive changes — new optional fields, new endpoints — ship without notice, so clients must ignore unknown response fields. Breaking changes are announced at https://annsa.ai/changelog. A formal deprecation window with `Deprecation` and `Sunset` response headers is not yet in force; do not infer one from this document.'
  contact:
    name: Annsa
    url: https://annsa.ai/contact
    email: support@annsa.ai
  license:
    name: Proprietary
    url: https://annsa.ai/terms
  termsOfService: https://annsa.ai/terms
servers:
- url: https://api.annsa.ai
  description: Production
security:
- sessionBearer: []
tags:
- name: Service
  description: Liveness.
paths:
  /health:
    get:
      operationId: getHealth
      summary: Liveness and build information
      description: Unauthenticated. Returns the running build so a client can tell which version answered.
      tags:
      - Service
      security: []
      responses:
        '200':
          description: The service is up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
              example:
                status: healthy
                name: Circuit API
                version: 0.1.0
                build_sha: unknown
                started_at: '2026-08-21T07:36:16.192017Z'
                environment: production
      parameters:
      - $ref: '#/components/parameters/AnnsaVersion'
components:
  schemas:
    HealthStatus:
      type: object
      title: HealthStatus
      required:
      - status
      properties:
        status:
          type: string
          examples:
          - healthy
        name:
          type: string
        version:
          type: string
        build_sha:
          type: string
          description: The deployed commit, where the build recorded one.
        started_at:
          type: string
          format: date-time
        environment:
          type: string
          examples:
          - production
  parameters:
    AnnsaVersion:
      name: Annsa-Version
      in: header
      required: false
      description: Pin the dated API contract. Omit it to use the current version. An unrecognised value is refused with 400 rather than downgraded. The version that served the request is echoed back in the same header. See https://annsa.ai/api-policy.
      schema:
        type: string
        enum:
        - '2026-08-22'
        example: '2026-08-22'
  securitySchemes:
    sessionBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A Supabase session token for a signed-in user. Grants that user's own workspace scope and nothing wider. This is not the survey key — sending a survey key here returns 401.
    oauth2:
      type: oauth2
      description: OAuth 2.0 for the MCP resource `https://app.annsa.ai/mcp`. PKCE with S256 is required. Clients may register themselves dynamically (RFC 7591); server metadata is published per RFC 8414 at `/.well-known/oauth-authorization-server` and protected-resource metadata per RFC 9728 at `/.well-known/oauth-protected-resource/mcp`.
      flows:
        authorizationCode:
          authorizationUrl: https://app.annsa.ai/mcp/auth
          tokenUrl: https://app.annsa.ai/mcp/token
          refreshUrl: https://app.annsa.ai/mcp/token
          scopes:
            read: Read priorities, specs, survey results and search.
            write: Change state — start building, mark shipped, share back with customers.
externalDocs:
  description: 'Versioning, deprecation and rate limits: how the version header works, what counts as a breaking change, the 90 days of notice before anything is removed, and the ceilings each endpoint carries.'
  url: https://annsa.ai/api-policy