naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    RACING_API_USERNAME: RACING_API_USERNAME
    RACING_API_PASSWORD: RACING_API_PASSWORD
capability:
  consumes:
  - type: http
    namespace: racing
    baseUri: https://api.theracingapi.com
    description: Horse racing data API with racecards, results, and analytics
    authentication:
      type: basic
      username: '{{RACING_API_USERNAME}}'
      password: '{{RACING_API_PASSWORD}}'
    resources:
    - name: courses
      path: /v1/courses
      description: Horse racing courses and regions
      operations:
      - name: get-regions
        method: GET
        description: Get a list of regions with region codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-courses
        method: GET
        description: Get a list of courses with course IDs and regions
        inputParameters:
        - name: region_codes
          in: query
          type: array
          required: false
          description: Filter by region codes (e.g. gb, ire)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: racecards
      path: /v1/racecards
      description: Race entry cards with runners, odds, and form
      operations:
      - name: get-free-racecards
        method: GET
        description: Get free racecards for today
        inputParameters:
        - name: day
          in: query
          type: string
          required: false
          description: Day filter (today, tomorrow)
        - name: region_codes
          in: query
          type: array
          required: false
          description: Filter by region codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-standard-racecards
        method: GET
        description: Get standard racecards with full runner details
        inputParameters:
        - name: day
          in: query
          type: string
          required: false
          description: Day filter
        - name: region_codes
          in: query
          type: array
          required: false
          description: Filter by region codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-pro-racecards
        method: GET
        description: Get pro racecards with advanced data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-big-race-racecards
        method: GET
        description: Get racecards for major races
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: results
      path: /v1/results
      description: Historical race results
      operations:
      - name: get-results
        method: GET
        description: Get historical race results with filters
        inputParameters:
        - name: start_date
          in: query
          type: string
          required: false
          description: Start date YYYY-MM-DD
        - name: end_date
          in: query
          type: string
          required: false
          description: End date YYYY-MM-DD
        - name: region
          in: query
          type: string
          required: false
          description: Region code
        - name: course
          in: query
          type: string
          required: false
          description: Course ID
        - name: type
          in: query
          type: string
          required: false
          description: Race type (flat, chase, hurdle, nh_flat)
        - name: limit
          in: query
          type: integer
          required: false
          description: Number of results to return
        - name: skip
          in: query
          type: integer
          required: false
          description: Pagination offset
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-todays-results
        method: GET
        description: Get today's race results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: horses
      path: /v1/horses
      description: Horse search and form data
      operations:
      - name: search-horses
        method: GET
        description: Search horses by name
        inputParameters:
        - name: name
          in: query
          type: string
          required: true
          description: Horse name to search
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-horse-results
        method: GET
        description: Get full historical results for a horse
        inputParameters:
        - name: horse_id
          in: path
          type: string
          required: true
          description: Horse identifier
        - name: start_date
          in: query
          type: string
          required: false
          description: Start date filter
        - name: end_date
          in: query
          type: string
          required: false
          description: End date filter
        - name: limit
          in: query
          type: integer
          required: false
          description: Number of results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: jockeys
      path: /v1/jockeys
      description: Jockey search and performance analytics
      operations:
      - name: search-jockeys
        method: GET
        description: Search jockeys by name
        inputParameters:
        - name: name
          in: query
          type: string
          required: true
          description: Jockey name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-jockey-results
        method: GET
        description: Get historical results for a jockey
        inputParameters:
        - name: jockey_id
          in: path
          type: string
          required: true
          description: Jockey identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-jockey-course-analysis
        method: GET
        description: Get jockey statistics by course
        inputParameters:
        - name: jockey_id
          in: path
          type: string
          required: true
          description: Jockey identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: trainers
      path: /v1/trainers
      description: Trainer search and performance analytics
      operations:
      - name: search-trainers
        method: GET
        description: Search trainers by name
        inputParameters:
        - name: name
          in: query
          type: string
          required: true
          description: Trainer name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-trainer-results
        method: GET
        description: Get historical results for a trainer
        inputParameters:
        - name: trainer_id
          in: path
          type: string
          required: true
          description: Trainer identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: owners
      path: /v1/owners
      description: Owner search and analytics
      operations:
      - name: search-owners
        method: GET
        description: Search owners by name
        inputParameters:
        - name: name
          in: query
          type: string
          required: true
          description: Owner name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sires
      path: /v1/sires
      description: Sire breeding analysis
      operations:
      - name: search-sires
        method: GET
        description: Search sires by name
        inputParameters:
        - name: name
          in: query
          type: string
          required: true
          description: Sire name
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-sire-class-analysis
        method: GET
        description: Get sire offspring statistics by race class
        inputParameters:
        - name: sire_id
          in: path
          type: string
          required: true
          description: Sire identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.