Sigma REST API — API Evangelist enrichment overlay

# API Evangelist enrichment overlay for the Sigma REST API.
# generated: '2026-08-27'
# method: generated
# source: derived from probes + docs recorded in this repo; extends openapi/sigma-computing-rest-api-openapi.yaml
# This overlay is ADDITIVE and NON-DESTRUCTIVE. It never mutates the provider's original spec.
overlay: 1.0.0
info:
  title: Sigma REST API — API Evangelist enrichment overlay
  version: 1.0.0
extends: ../openapi/sigma-computing-rest-api-openapi.yaml
actions:
- target: $.info
  description: >-
    Record where each published contract actually came from, and that the two Sigma publishes are not identical.
  update:
    x-apievangelist-provenance:
      harvested: '2026-08-27'
      source_url: https://help.sigmacomputing.com/openapi/sigma-rest-api.yaml
      discovered_via: RFC 9727 API catalog at https://help.sigmacomputing.com/.well-known/api-catalog
      sibling_contract: https://help.sigmacomputing.com/openapi/code-representation.yaml
      docs_download_contract:
        title: Sigma Computing Public REST API
        version: 2.0.0
        note: >-
          The "Download OpenAPI spec" button on the API reference serves a THIRD, differently-titled document from a
          presigned Fern asset URL. It is a near-superset (203 paths / 286 operations vs 193 / 274 here) and adds the
          /v3alpha/ surface and the workbook code-representation paths, but it also OMITS four paths this document
          carries (/v2/dataModels/{dataModelId}/elements/{elementId}/query,
          /v2/organizations/settings/bulkCopy, /v2/organizations/settings/licenseUpgradeRequests,
          /v2/organizations/settings/publicEmbeds). Neither is a superset of the other.
        saved_as: openapi/_original/sigma-computing-public-rest-api-openapi.json
- target: $.info
  description: Name the regional base-URL requirement that the servers[] block implies but does not explain.
  update:
    x-apievangelist-base-url-guidance: >-
      There is no single base URL. Each Sigma organization is pinned to exactly one of the thirteen servers listed in
      this document, across GCP, AWS and Azure. Customers read theirs from Administration > Developer Access >
      API base URL. Hard-coding https://api.sigmacomputing.com will fail for most organizations.
- target: $.info
  description: Record the runtime semantics that are documented in prose but absent from the contract.
  update:
    x-apievangelist-runtime-semantics:
      authentication:
        flow: OAuth 2.0 client credentials
        token_endpoint: '{baseURL}/v2/auth/token'
        token_ttl_seconds: 3600
      rate_limits:
        published_in_contract: false
        documented_at: https://help.sigmacomputing.com/reference/get-started-sigma-api
        limits:
        - endpoint: POST /v2/auth/token
          limit: 1
          window: 1s
        - endpoint: POST /v2/workbooks/{workbookId}/export
          limit: 400
          window: 1m
        - endpoint: POST /v2/reports/{reportId}/export
          limit: 400
          window: 1m
        - endpoint: POST /v2/workbooks/{workbookId}/send
          limit: 100
          window: 1m
        - endpoint: POST /v2/reports/{reportId}/send
          limit: 100
          window: 1m
        - endpoint: GET /v2/query/{queryId}/download
          limit: 400
          window: 1m
        response_headers: []
        note: No X-RateLimit-*, RateLimit-* or Retry-After headers are defined or documented.
      pagination:
        default_page_size: 50
        max_page_size: 1000
        styles:
        - style: offset
          params: [page, limit]
        - style: cursor
          params: [pageToken, pageSize]
      idempotency:
        supported: false
        note: No Idempotency-Key header anywhere in the contract or the docs.
      error_envelope:
        media_type: application/json
        rfc9457: false
        fields: [requestId, message, code]
        note: >-
          Every operation declares only a `default` error response. No operation declares an explicit 4xx or 5xx,
          so a generated client cannot enumerate an operation's failure modes.
- target: $.info
  description: Record the reversibility posture, which nothing in the contract expresses.
  update:
    x-apievangelist-reversibility:
      grade: verified
      recoverable:
      - surface: workbook content
        reversal_operation: restoreWorkbookVersion
        window: unlimited
        window_source: https://help.sigmacomputing.com/docs/workbook-versions-and-version-history
      partially_recoverable:
      - surface: deployment policies
        note: DELETE is named archiveDeployment, but no un-archive operation is published.
      - surface: data model source bindings
        note: swapDataModelSources is symmetric; re-issue the inverse call.
      irreversible:
      - DELETE /v2/members/{memberId}
      - DELETE /v2/teams/{teamId}
      - DELETE /v2/connections/{connectionId}
      - DELETE /v2/grants/{grantId}
      - DELETE /v2/workspaces/{workspaceId}
      - DELETE /v2/api-credentials/{apiCredentialId}
      agent_guidance: >-
        Prefer POST /v2/members/{memberId}/revoke (revokeMemberTokens) over DELETE /v2/members/{memberId}. Identity,
        access and connection deletes have no published restore path and no stated retention window; escalate to a
        human before issuing one.
- target: $.info
  description: Point at the companion agent surfaces this contract does not mention.
  update:
    x-apievangelist-agent-surfaces:
      mcp_server: https://api.sigmacomputing.com/mcp
      mcp_auth: OAuth 2.1 authorization code + PKCE, scope mcp:access
      agent_skills: https://github.com/sigmacomputing/sigma-agent-skills
      cli: sigma (generated from this same OpenAPI at runtime)
      llms_txt: https://help.sigmacomputing.com/llms.txt
      api_catalog: https://help.sigmacomputing.com/.well-known/api-catalog
      agent_card: none served
- target: $.paths['/v2/auth/token']['post']
  description: Flag the token endpoint's severe rate limit and token lifetime at the operation itself.
  update:
    x-apievangelist-notes:
      rate_limit: 1 request per second
      token_ttl_seconds: 3600
      guidance: >-
        Cache the bearer token for its full hour. Minting a token per request will trip the 1 rps limit almost
        immediately in any concurrent client.
- target: $.paths['/v2/webhooks/{workbookId}/{sequenceId}']['post']
  description: Record the asynchronous contract of the inbound webhook trigger.
  update:
    x-apievangelist-notes:
      direction: inbound
      response: 202 Accepted with an action trace ID
      completion_signal: none
      guidance: >-
        Sigma enqueues the action sequence and returns immediately. There is no published callback and no polling
        endpoint for the trace ID, so a caller cannot confirm the sequence succeeded.
      payload_schema_discovery: GET /v2/webhooks/{workbookId}/{sequenceId}/schema
      authentication: REST API bearer token (default) or configurable HMAC signature verification