API Evangelist enhancements for the Goalkeeper API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Goalkeeper API
  version: 1.0.0
extends: openapi/poggio-labs-goalkeeper-openapi.json
x-provenance:
  generated: '2026-08-13'
  method: generated
  source: >-
    Derived from artifacts in this repo — conventions/poggio-labs-goalkeeper-conventions.yml,
    scopes/poggio-labs-goalkeeper-scopes.yml, errors/poggio-labs-goalkeeper-problem-types.yml,
    mcp/poggio-labs-goalkeeper-tool-crosswalk.yml — plus the published docs at docs.gkeeper.ai.
    The harvested spec is never mutated; these are our additions, held separately.
actions:
- target: $.info
  update:
    x-apievangelist-slug: poggio-labs
    x-apievangelist-product: Goalkeeper
    x-apievangelist-source: https://github.com/poggiolabs/goalkeeper/blob/v0.5.0/services/api/openapi.json
    x-apievangelist-license: Apache-2.0
    x-apievangelist-docs: https://docs.gkeeper.ai/docs/api/rest-api
    x-apievangelist-note: >-
      info.version in the published document is 0.0.0 — a build placeholder. The real
      released version at harvest time was 0.5.0 (git tag v0.5.0, 2026-08-11).
- target: $.servers
  update:
    x-apievangelist-deployment: self-hosted
    x-apievangelist-note: >-
      The only server declared is http://localhost:3001 (local development). Poggio Labs
      operates no hosted Goalkeeper API, so there is no production base URL to add — the
      operator supplies their own host. This is recorded rather than repaired.
- target: $.components.securitySchemes.bearerAuth
  update:
    x-apievangelist-scopes: scopes/poggio-labs-goalkeeper-scopes.yml
    x-apievangelist-scope-values: [goals:read, goals:write, goals:read:all, goals:write:all,
      labels:read, labels:write]
    x-apievangelist-token-policy: >-
      Opaque, SHA-256 hashed, 1–365 day expiry (default 90), immediately revocable;
      deliberately not a JWT.
- target: $.paths['/v1/goals/{goalId}/updates'].post
  update:
    x-apievangelist-idempotency:
      supported: true
      field: idempotencyKey
      location: requestBody
      concurrency_field: expectedRevision
      note: >-
        Both fields are REQUIRED. Re-drive a rejected write by re-reading the goal's
        revision and retrying with the same idempotencyKey.
    x-apievangelist-mcp-tool: report_goal_update
- target: $.paths['/v1/goals'].get
  update:
    x-apievangelist-mcp-tool: list_goals
    x-apievangelist-pagination: none
- target: $.paths['/v1/goals'].post
  update:
    x-apievangelist-mcp-tool: create_goal
- target: $.paths['/v1/goals/{goalId}'].get
  update:
    x-apievangelist-mcp-tool: get_goal
- target: $.paths['/v1/goals/{goalId}'].patch
  update:
    x-apievangelist-mcp-tool: update_goal
- target: $.paths['/v1/goals/{goalId}'].delete
  update:
    x-apievangelist-mcp-tool: null
    x-apievangelist-note: >-
      Intentionally not exposed to agents — the MCP surface archives a goal through
      report_goal_update instead of hard-deleting it.
- target: $.components.schemas.Error
  update:
    x-apievangelist-error-catalog: errors/poggio-labs-goalkeeper-problem-types.yml
    x-apievangelist-rfc9457: false