Annsa Agents API

openapi: 3.2.0
info:
  title: Annsa Agents 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: Agents
  description: The MCP surface — ranked priorities, codebase-aware specs, search.
paths:
  /mcp:
    post:
      operationId: callMcp
      summary: Call an Annsa MCP tool (JSON-RPC 2.0)
      description: 'The agent surface. A Streamable HTTP MCP endpoint exposing eight tools:


        - `annsa.priorities` — what to work on next: ranked priorities with the evidence behind each

        - `annsa.spec` — the plan for one priority: what to build, files to touch, Done When

        - `annsa.ask` — ask about your feedback, priorities, specs, customers, surveys or Annsa itself

        - `annsa.work` — everyday work on a priority you hold: claim, write, note, verify, ship, escalate

        - `annsa.file` — add new rows: feedback, findings, proposed priorities

        - `annsa.decide` — approve, answer, sign, record a principle

        - `annsa.board` — arrange the board: stage, severity, merge, park, bets

        - `annsa.share` — email the customers who asked; it can''t be unsent


        This is the only Annsa surface with scoped authorization. Obtain a token with OAuth 2.0 authorization code + PKCE (S256); clients may register themselves at the `registration_endpoint`. `read` covers priorities, specs and search; `write` covers state changes and Share Back.


        An unauthenticated request returns 401 with a `WWW-Authenticate: Bearer` header naming the protected-resource metadata document, so a client can discover how to authenticate from one request.


        Note the different host: this endpoint is served from `https://app.annsa.ai`, not `api.annsa.ai`.'
      tags:
      - Agents
      servers:
      - url: https://app.annsa.ai
        description: MCP resource server
      security:
      - oauth2:
        - read
      - oauth2:
        - read
        - write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              listTools:
                summary: List the available tools
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: tools/list
              callTool:
                summary: Ask what to build next
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/call
                  params:
                    name: annsa.priorities
                    arguments: {}
      responses:
        '200':
          description: A JSON-RPC 2.0 response, or an SSE stream when the client accepts `text/event-stream`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '401':
          description: Missing or invalid bearer token. Carries `WWW-Authenticate` naming the protected-resource metadata.
          headers:
            WWW-Authenticate:
              description: e.g. `Bearer realm="Annsa MCP", resource_metadata="https://app.annsa.ai/.well-known/oauth-protected-resource/mcp"`
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      parameters:
      - $ref: '#/components/parameters/AnnsaVersion'
components:
  schemas:
    JsonRpcRequest:
      type: object
      title: JsonRpcRequest
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - integer
        method:
          type: string
          examples:
          - initialize
          - tools/list
          - tools/call
        params:
          type: object
          additionalProperties: true
    JsonRpcResponse:
      type: object
      title: JsonRpcResponse
      required:
      - jsonrpc
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - integer
        result:
          type: object
          additionalProperties: true
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    Error:
      type: object
      title: Error
      description: The single error shape every endpoint returns. `detail` is human-readable and may change; branch on the HTTP status code instead.
      required:
      - detail
      properties:
        detail:
          type: string
          description: What went wrong, in plain language.
          examples:
          - Invalid API key
  responses:
    Forbidden:
      description: The credential is valid but lacks the scope for this call.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    RateLimitLimit:
      description: Requests permitted in the window.
      schema:
        type: integer
        example: 5000
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 4999
    RateLimitReset:
      description: Seconds until the window resets. Delta-seconds, per the IETF draft — not an absolute timestamp.
      schema:
        type: integer
        example: 3599
    RateLimit:
      description: Your position in the current window, as the combined field from the later IETF drafts. Present on any response where the limit was actually evaluated.
      schema:
        type: string
        example: limit=5000, remaining=4999, reset=3599
  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