API Evangelist enhancements for SkipOdds

overlay: 1.0.0
info:
  title: API Evangelist enhancements for SkipOdds
  version: 1.0.0
x-provenance:
  generated: '2026-08-11'
  method: generated
  source: >-
    Derived from openapi/skipodds-openapi.yml plus facts published at https://skipodds.com/docs,
    /docs/fixtures, /docs/movement, /docs/outrights, /docs/alerts, /docs/limits, and one live
    unauthenticated response. Every value below is stated by the provider somewhere public; none is
    invented. This overlay is never applied to the harvested original.
extends: openapi/skipodds-openapi.yml
actions:
  - target: $.info
    description: Record the independent API Evangelist profile and the surfaces the spec omits.
    update:
      x-apievangelist-profile: https://apis.io/provider/skipodds
      x-apievangelist-reviewed: '2026-08-11'
      x-mcp-server: https://skipodds.com/mcp
      x-rate-limit-signal: >-
        No RateLimit-* response headers. Remaining daily allowance is returned in the response body as
        requests_remaining_today; exhaustion is 429 {"error":"quota_exceeded"} with no Retry-After.
      x-idempotency: >-
        Not supported and not documented. Ten of eleven operations are GET; POST /v1/alerts/webhooks
        has no de-duplication guarantee, so a retried registration should be assumed to create a
        second webhook.

  - target: $
    description: Declare the tag vocabulary the spec omits entirely — no operation carries a tag.
    update:
      tags:
        - name: Fixtures
          description: Matches, games and fights with the de-vigged SkipOdds Index.
        - name: Movement
          description: How the de-vigged consensus moved over a time window.
        - name: Outrights
          description: Tournament-winner markets, normalised across the field that can still win.
        - name: Golf
          description: Field-wide golf outright probabilities.
        - name: Alerts
          description: Movement-alert webhook registration and management (paid tiers).

  - target: $.paths['/v1/fixtures'].get
    update:
      tags: [Fixtures]
  - target: $.paths['/v1/fixtures/{id}'].get
    update:
      tags: [Fixtures]
  - target: $.paths['/v1/{sport}/fixtures'].get
    update:
      tags: [Fixtures]
  - target: $.paths['/v1/{sport}/fixtures/{id}'].get
    update:
      tags: [Fixtures]
  - target: $.paths['/v1/fixtures/{id}/movement'].get
    update:
      tags: [Movement]
  - target: $.paths['/v1/{sport}/fixtures/{id}/movement'].get
    update:
      tags: [Movement]
  - target: $.paths['/v1/outrights'].get
    update:
      tags: [Outrights]
  - target: $.paths['/v1/golf/tournaments'].get
    update:
      tags: [Golf, Outrights]
  - target: $.paths['/v1/golf/tournaments/{key}'].get
    update:
      tags: [Golf, Outrights]
  - target: $.paths['/v1/alerts/webhooks'].get
    update:
      tags: [Alerts]
  - target: $.paths['/v1/alerts/webhooks'].post
    update:
      tags: [Alerts]

  - target: $.paths['/v1/fixtures'].get.parameters[?(@.name=='limit')].schema
    description: The 1-50 range is documented at /docs/fixtures but absent from the schema.
    update:
      minimum: 1
      maximum: 50
  - target: $.paths['/v1/{sport}/fixtures'].get.parameters[?(@.name=='limit')].schema
    update:
      minimum: 1
      maximum: 50

  - target: $.paths['/v1/fixtures/{id}/movement'].get.parameters[?(@.name=='hours')]
    description: Default and tier-gated caps documented at /docs/movement but absent from the schema.
    update:
      schema:
        type: integer
        default: 24
        minimum: 1
        maximum: 336
      description: >-
        Lookback window in hours. Default 24. Capped at 72 on Demo/Free/Starter/Pro and 336 (14 days)
        on the Scale tier.
  - target: $.paths['/v1/{sport}/fixtures/{id}/movement'].get.parameters[?(@.name=='hours')]
    update:
      schema:
        type: integer
        default: 24
        minimum: 1
        maximum: 336
      description: >-
        Lookback window in hours. Default 24. Capped at 72 on Demo/Free/Starter/Pro and 336 (14 days)
        on the Scale tier.

  - target: $.paths['/v1/{sport}/fixtures'].get.parameters[?(@.name=='sport')].schema
    description: >-
      The sport values are enumerated on the MCP tool schema the provider serves at
      https://skipodds.com/mcp, but the OpenAPI leaves the path parameter as a free string.
    update:
      enum:
        - tennis
        - cricket
        - rugby
        - baseball
        - football
        - basketball
        - hockey
        - college-football
        - college-basketball
        - mma
        - boxing
  - target: $.paths['/v1/{sport}/fixtures/{id}'].get.parameters[?(@.name=='sport')].schema
    update:
      enum: [tennis, cricket, rugby, baseball, football, basketball, hockey, college-football, college-basketball, mma, boxing]
  - target: $.paths['/v1/{sport}/fixtures/{id}/movement'].get.parameters[?(@.name=='sport')].schema
    update:
      enum: [tennis, cricket, rugby, baseball, football, basketball, hockey, college-football, college-basketball, mma, boxing]

  - target: $.paths['/v1/alerts/webhooks'].post
    description: >-
      Record the range and default the docs publish for the threshold, and the naming disagreement
      between the docs (threshold_points) and the spec (threshold).
    update:
      x-field-naming-conflict: >-
        The docs at https://skipodds.com/docs/alerts name this field threshold_points; the OpenAPI
        requestBody names it threshold. The two published sources disagree.
      x-threshold-range: 1-20 probability points, default 3
      x-tier-slots: 'Starter 2, Pro 5, Scale 20'
      x-delivery: >-
        A Discord webhook URL receives a formatted Discord message; any other HTTPS endpoint receives
        JSON. No signature or shared secret is published for receiver-side verification. Endpoints
        failing 10 consecutive deliveries are deactivated.

  - target: $.components.schemas.Consensus
    description: >-
      Record the polymorphism the schema does not express. Live responses and the docs show p1/p2 for
      tennis and combat sports and players[] for golf; only the 3-way home/draw/away variant is modelled.
    update:
      x-market-variants:
        three_way: [home, draw, away]
        moneyline: [home, away]
        two_way: [p1, p2]
        field: [players]
      x-variant-note: >-
        The key set varies by market shape. A client generated from this schema will not model tennis,
        MMA, boxing or golf responses correctly.

  - target: $.components.securitySchemes
    description: Record that the same static key is used for both schemes.
    update:
      x-credential-note: >-
        BearerAuth and ApiKeyHeader accept the SAME static API key; there is no OAuth flow and no token
        exchange. Bearer is preferred; x-api-key is retained for existing integrations. The key must
        never be placed in a query string. Note the spec also redundantly declares x-api-key as an
        optional header PARAMETER on every operation in addition to the security scheme.