overlay: 1.0.0
info:
  title: API Evangelist enhancements for marginalia public API
  version: 1.0.0
  description: >-
    Non-destructive annotations over the provider's generated OpenAPI 3.0.3 (fetched verbatim from
    https://marginalia.polycode.co.uk/api/openapi.json on 2026-09-19). The original is never mutated; these actions
    add catalog metadata, tags grouped by resource, the X-API-Key security scheme the agent card declares but the
    spec omits, and the observed 401/404 error responses. Generated by API Evangelist (method: generated).
extends: openapi/polycode-co-uk-marginalia-openapi.json
actions:
- target: $.info
  update:
    x-apievangelist-slug: polycode-co-uk
    x-apievangelist-provider: Polycode Limited
    x-apievangelist-fetched: '2026-09-19'
    x-apievangelist-license-note: Code is AGPL-3.0-only; visitor contributions to the shared graph are CC-BY-SA 4.0.
    contact:
      name: Polycode Limited (operator)
      email: antony@polycode.co.uk
      url: https://marginalia.polycode.co.uk/developers
- target: $
  update:
    tags:
    - {name: Chat, description: Async one-turn chat, task polling, and the OpenAI-shaped mechanical completion shim.}
    - {name: Graphs, description: Memory graphs — the shared default graph and key-bound private graphs.}
    - {name: Sessions, description: Session search, history, meta and introductions.}
    - {name: Memory, description: Insights, daily summaries, typed-entity views, turns and flags.}
    - {name: Projects, description: Research projects a graph tends over time and their files.}
    - {name: Keys, description: Private-graph API keys (Tier-1 login).}
    - {name: Ops, description: Deployment status, budget, usage and diverts.}
    - {name: Admin, description: Operator-only actions.}
    - {name: Hooks, description: Inbound webhook receivers for bound repositories and collectors.}
- target: $.components
  update:
    securitySchemes:
      apiKey:
        type: apiKey
        in: header
        name: X-API-Key
        description: >-
          Declared in the A2A agent card, not in the spec. Optional today; routes a request to the private graph the key
          is bound to. Observed live: GET /api/keys/whoami without it returns 401 {"error":"send the key as X-API-Key"}.
      cognitoLogin:
        type: openIdConnect
        openIdConnectUrl: https://eu-west-24yw02qhzm.auth.eu-west-2.amazoncognito.com/.well-known/openid-configuration
        description: >-
          Tier-1 browser login (Google via Amazon Cognito, scope openid email profile), started at /auth/login. Gates
          key minting, private graphs and per-user defaults. Observed live: GET /api/keys without it returns 401
          {"error":"login required"}. The openid-configuration URL is the conventional Cognito location and was not probed.
    responses:
      Unauthorized:
        description: Login or X-API-Key required.
        content:
          application/json:
            schema: {type: object, properties: {error: {type: string}}}
            examples:
              loginRequired: {value: {error: login required}}
              keyRequired: {value: {error: send the key as X-API-Key}}
      NotFound:
        description: Unknown route or resource.
        content:
          application/json:
            schema: {type: object, properties: {error: {type: string}, path: {type: string}, method: {type: string}}}
            example: {error: not found, path: /api/docs, method: GET}
- target: $.paths['/api/chat'].post
  update: {tags: [Chat]}
- target: $.paths['/api/chat/result'].get
  update: {tags: [Chat]}
- target: $.paths['/api/v1/chat/completions'].post
  update: {tags: [Chat]}
- target: $.paths['/api/graphs'].get
  update: {tags: [Graphs]}
- target: $.paths['/api/graphs/default'].get
  update: {tags: [Graphs]}
- target: $.paths['/api/sessions'].get
  update: {tags: [Sessions]}
- target: $.paths['/api/projects'].get
  update: {tags: [Projects]}
- target: $.paths['/api/keys'].get
  update:
    tags: [Keys]
    security: [{cognitoLogin: []}]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/api/keys/whoami'].get
  update:
    tags: [Keys]
    security: [{apiKey: []}]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/api/status'].get
  update: {tags: [Ops]}
- target: $.paths['/api/budget'].get
  update: {tags: [Ops]}