API Evangelist enhancements for Salesgraph REST API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Salesgraph REST API
  version: 1.1.0
extends: openapi/_original/salesgraph-openapi.yml
x-provenance:
  generated: '2026-08-13'
  method: generated
  source: openapi/_original/salesgraph-openapi.yml
  applies_to:
    - openapi/salesgraph-commands-api-openapi.yml
    - openapi/salesgraph-runs-api-openapi.yml
    - openapi/salesgraph-audit-api-openapi.yml
    - openapi/salesgraph-oms-api-openapi.yml
    - openapi/salesgraph-status-api-openapi.yml
actions:
  - target: $.info
    update:
      x-apievangelist-provenance: >
        Spec generated by the API Evangelist enrichment pipeline from the published Salesgraph
        REST API reference (docs.salesgraph.com/reference/rest-api) and the provider's Agent
        Skill at docs.salesgraph.com/.well-known/agent-skills/salesgraph/skill.md; the provider's
        own /api-reference/openapi.json is still a Mintlify "OpenAPI Plant Store" placeholder
        (re-probed 2026-08-13).
      x-mcp-server: https://salesgraph.com/api/mcp
      x-agent-card: https://docs.salesgraph.com/.well-known/agent-card.json
      x-status-api: https://salesgraph.com/api/status
  - target: $.info
    update:
      x-response-media-type: >
        text/markdown on command endpoints; application/json on OMS endpoints and on /api/status
      x-async-model: run-and-poll (X-Run-Id / X-Run-Status headers; poll /api/v1/runs/{kind}/{id})
      x-idempotency: >
        idempotencyKey body field on OMS watch creation only; no Idempotency-Key header and no
        idempotency contract on the command endpoints
      x-pagination: >
        opaque cursor; pageToken/nextPageToken on OMS object pages, cursor/nextCursor on OMS
        watch pages, null terminates
      x-rate-limit-signal: >
        HTTP 429 per organization; no limit, window, Retry-After or RateLimit-* header is
        published
  - target: $.paths['/api/status'].get
    update:
      x-unauthenticated: true
      x-agent-note: >
        The only Salesgraph operation callable without an API key. An agent should read it before
        reporting a Salesgraph outage, since the MCP server itself cannot answer when it is down.
  - target: $.paths['/api/v1/oms/watches'].post
    update:
      x-idempotency-field: idempotencyKey
      x-cost-cap-field: monthlyCostCapMicros
      x-agent-note: >
        Always send idempotencyKey — this is the single idempotency contract Salesgraph
        publishes, and a retry without it creates a duplicate watch.
  - target: $.paths['/api/v1/oms/actions'].post
    update:
      x-human-in-the-loop: required
      x-agent-note: >
        The 202 means the request is queued for a person to approve, not that the write
        succeeded. Nothing is applied to the organization's records until approval.
  - target: $.paths['/api/v1/oms/get'].post
    update:
      x-key-form: 'public key (e.g. domain:acme.com), never an internal primary key'