The Racing API Horse Racing Analytics

naftiko: "1.0.0-alpha1"

info:
  label: "The Racing API Horse Racing Analytics"
  description: "Unified workflow for horse racing research, form analysis, and racecard review. Combines racecards, results, horse form, jockey and trainer statistics for racing analysts and application developers."
  tags:
    - Horse Racing
    - Sports
    - Analytics
    - Racecards
    - Statistics
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      RACING_API_USERNAME: RACING_API_USERNAME
      RACING_API_PASSWORD: RACING_API_PASSWORD

capability:
  consumes:
    - import: racing
      location: ./shared/the-racing-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: racing-analytics-api
      description: "Unified REST API for horse racing analytics, form research, and racecard review."
      resources:
        - path: /v1/racecards
          name: racecards
          description: "Today's and future race entry cards"
          operations:
            - method: GET
              name: list-racecards
              description: "Get racecards for today or tomorrow"
              call: "racing.get-standard-racecards"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/results
          name: results
          description: "Historical race results"
          operations:
            - method: GET
              name: list-results
              description: "Get historical race results with filters"
              call: "racing.get-results"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/courses
          name: courses
          description: "Racing courses and regions"
          operations:
            - method: GET
              name: list-courses
              description: "List all racing courses"
              call: "racing.get-courses"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/horses
          name: horses
          description: "Horse search and form data"
          operations:
            - method: GET
              name: search-horses
              description: "Search for horses by name"
              call: "racing.search-horses"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/horses/{id}
          name: horse-detail
          description: "Individual horse form and history"
          operations:
            - method: GET
              name: get-horse-results
              description: "Get historical results for a specific horse"
              call: "racing.get-horse-results"
              with:
                horse_id: "rest.id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/jockeys
          name: jockeys
          description: "Jockey search and statistics"
          operations:
            - method: GET
              name: search-jockeys
              description: "Search for jockeys by name"
              call: "racing.search-jockeys"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/trainers
          name: trainers
          description: "Trainer search and statistics"
          operations:
            - method: GET
              name: search-trainers
              description: "Search for trainers by name"
              call: "racing.search-trainers"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: racing-analytics-mcp
      transport: http
      description: "MCP server for AI-assisted horse racing research and form analysis."
      tools:
        - name: list-racecards
          description: "Get today's or tomorrow's race cards with runners, odds, and form"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-standard-racecards"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-free-racecards
          description: "Get free-tier racecards for basic race information"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-free-racecards"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-big-race-cards
          description: "Get racecards for major featured races"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-big-race-racecards"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-results
          description: "Get historical race results filtered by date, region, course, or race type"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-results"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-todays-results
          description: "Get all race results from today"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-todays-results"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-courses
          description: "List all available racing courses with IDs and regions"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-courses"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-regions
          description: "List all racing regions with region codes"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-regions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-horses
          description: "Search for a horse by name to find its ID for detailed form queries"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.search-horses"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-horse-results
          description: "Get full historical race results for a specific horse"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-horse-results"
          with:
            horse_id: "tools.horse_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-jockeys
          description: "Search for a jockey by name"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.search-jockeys"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-jockey-results
          description: "Get historical riding results for a jockey"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-jockey-results"
          with:
            jockey_id: "tools.jockey_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-jockey-course-analysis
          description: "Get jockey performance statistics broken down by course"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-jockey-course-analysis"
          with:
            jockey_id: "tools.jockey_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-trainers
          description: "Search for a trainer by name"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.search-trainers"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-trainer-results
          description: "Get historical training results for a trainer"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-trainer-results"
          with:
            trainer_id: "tools.trainer_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-owners
          description: "Search for a horse owner by name"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.search-owners"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: search-sires
          description: "Search for a sire by name for breeding analysis"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.search-sires"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-sire-class-analysis
          description: "Get sire offspring performance statistics by race class"
          hints:
            readOnly: true
            openWorld: true
          call: "racing.get-sire-class-analysis"
          with:
            sire_id: "tools.sire_id"
          outputParameters:
            - type: object
              mapping: "$."