openapi: 3.1.0
info:
  title: RunSignup Corrals Results API
  description: The RunSignup REST API provides access to race and event management operations for the RunSignup platform. It enables race directors, timing companies, affiliates, and technology partners to integrate race registration, participant management, results posting, bib and chip assignment, division management, team management, fundraising, volunteer management, and user account management. The API covers 100+ endpoints across 29 categories. Authentication uses OAuth 2.0 (preferred) or permanent API keys for partners and timers. The base URL is https://runsignup.com/Rest and responses are available in JSON or XML format.
  version: '1.0'
  contact:
    name: RunSignup Support
    url: https://runsignup.com/support
  termsOfService: https://runsignup.com/terms
servers:
- url: https://runsignup.com/Rest
  description: RunSignup REST API
security:
- OAuth2: []
- apiKeyAuth: []
tags:
- name: Results
  description: Submit, import, and retrieve race results including finishing times, result sets, and full results with place and time data.
paths:
  /race/{race_id}/results/get-results:
    get:
      operationId: getRaceResults
      summary: Get Race Results
      description: Returns all results across all result sets for a race. Includes placing, finish time, chip time, and division results for each participant.
      tags:
      - Results
      parameters:
      - $ref: '#/components/parameters/RaceId'
      - name: event_id
        in: query
        description: Filter by specific event ID
        schema:
          type: integer
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
      responses:
        '200':
          description: Race results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /race/{race_id}/results/full-results:
    post:
      operationId: postRaceResults
      summary: Post Full Race Results
      description: Submits complete race results for an event. Each result includes registration ID, place, clock time, and optionally chip time. This is the primary endpoint used by timing systems to upload results.
      tags:
      - Results
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FullResultsRequest'
      responses:
        '200':
          description: Results posted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsPostResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /race/{race_id}/results/finishing-times:
    post:
      operationId: postFinishingTimes
      summary: Post Finishing Times
      description: Posts finishing time data for participants in an event. Designed for real-time results updates from timing systems during or after a race.
      tags:
      - Results
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinishingTimesRequest'
      responses:
        '200':
          description: Finishing times posted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsPostResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /race/{race_id}/results/start-time:
    post:
      operationId: setRaceStartTime
      summary: Set Race Start Time
      description: Sets the official start time for a race event. Used by timing systems to record the gun time or wave start time.
      tags:
      - Results
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_id
              - start_time
              properties:
                event_id:
                  type: integer
                  description: The event to set start time for
                start_time:
                  type: string
                  description: Start time in format HH:MM:SS.ms
      responses:
        '200':
          description: Start time set
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /race/{race_id}/results/clear-results:
    post:
      operationId: clearRaceResults
      summary: Clear Race Results
      description: Removes all results for a specified result set. Use with caution as this operation cannot be undone.
      tags:
      - Results
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                result_set_id:
                  type: integer
                event_id:
                  type: integer
      responses:
        '200':
          description: Results cleared
        '401':
          $ref: '#/components/responses/Unauthorized'
  /race/{race_id}/results/csv-import:
    post:
      operationId: importResultsFromCsv
      summary: Import Results from CSV
      description: Imports race results from a CSV file upload. The CSV must include at minimum bib number and finish time columns.
      tags:
      - Results
      parameters:
      - $ref: '#/components/parameters/RaceId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file with results data
                event_id:
                  type: integer
      responses:
        '200':
          description: Results imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsPostResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ResultsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
        total_results:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        error_msg:
          type: string
          description: Human-readable error message
    FinishingTimesRequest:
      type: object
      required:
      - event_id
      - times
      properties:
        event_id:
          type: integer
        times:
          type: array
          items:
            type: object
            properties:
              chip_num:
                type: string
              bib_num:
                type: string
              finish_time:
                type: string
    ResultsPostResponse:
      type: object
      properties:
        results_submitted:
          type: integer
        errors:
          type: integer
        error_details:
          type: array
          items:
            type: object
            properties:
              registration_id:
                type: integer
              message:
                type: string
    Result:
      type: object
      properties:
        result_id:
          type: integer
        registration_id:
          type: integer
        bib_num:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        clock_time:
          type: string
          description: Clock time from gun start (HH:MM:SS.ms)
        chip_time:
          type: string
          description: Net chip time (HH:MM:SS.ms)
        place_overall:
          type: integer
        place_gender:
          type: integer
        place_division:
          type: integer
        gender:
          type: string
        age:
          type: integer
        event_id:
          type: integer
        pace:
          type: string
    FullResultsRequest:
      type: object
      required:
      - event_id
      - results
      properties:
        event_id:
          type: integer
          description: The event to post results for
        result_set_name:
          type: string
          description: Name for this result set (defaults to "Official")
        results:
          type: array
          items:
            type: object
            required:
            - registration_id
            - place
            - clock_time
            properties:
              registration_id:
                type: integer
              bib_num:
                type: string
              place:
                type: integer
                description: Overall finish place
              clock_time:
                type: string
                description: Gun/clock time (HH:MM:SS.ms)
              chip_time:
                type: string
                description: Net chip time (HH:MM:SS.ms)
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    RaceId:
      name: race_id
      in: path
      required: true
      description: The unique ID of the race
      schema:
        type: integer
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication (preferred)
      flows:
        authorizationCode:
          authorizationUrl: https://runsignup.com/OAuth/Authorize
          tokenUrl: https://runsignup.com/OAuth/Token
          scopes:
            read: Read access to race and participant data
            write: Write access to race and participant data
    apiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: Permanent API key for affiliates, partners, and timers. Pass api_key and api_secret as query parameters.
externalDocs:
  description: RunSignup API Documentation
  url: https://runsignup.com/API