openapi: 3.0.3
info:
  title: SpaceX Capsules Launches API
  description: The SpaceX API is an open-source REST API providing comprehensive data about SpaceX missions, rockets, capsules, cores, crew, launchpads, landing pads, payloads, ships, and the Starlink satellite constellation. It covers all past and upcoming launches with detailed mission data. No authentication is required.
  version: 5.0.0
  contact:
    name: SpaceX API Community
    url: https://github.com/r-spacex/SpaceX-API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.spacexdata.com/v5
  description: SpaceX API v5 production server
tags:
- name: Launches
  description: SpaceX mission launch data
paths:
  /launches:
    get:
      operationId: listLaunches
      summary: List All Launches
      description: Returns all SpaceX launches including past and upcoming missions
      tags:
      - Launches
      responses:
        '200':
          description: Array of launch objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Launch'
  /launches/latest:
    get:
      operationId: getLatestLaunch
      summary: Get Latest Launch
      description: Returns the most recent SpaceX launch
      tags:
      - Launches
      responses:
        '200':
          description: Most recent launch object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Launch'
  /launches/next:
    get:
      operationId: getNextLaunch
      summary: Get Next Launch
      description: Returns the next scheduled SpaceX launch
      tags:
      - Launches
      responses:
        '200':
          description: Next scheduled launch object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Launch'
  /launches/upcoming:
    get:
      operationId: listUpcomingLaunches
      summary: List Upcoming Launches
      description: Returns all future scheduled SpaceX launches
      tags:
      - Launches
      responses:
        '200':
          description: Array of upcoming launch objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Launch'
  /launches/past:
    get:
      operationId: listPastLaunches
      summary: List Past Launches
      description: Returns all past SpaceX launches
      tags:
      - Launches
      responses:
        '200':
          description: Array of past launch objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Launch'
  /launches/{id}:
    get:
      operationId: getLaunch
      summary: Get Launch
      description: Returns a single SpaceX launch by its unique ID
      tags:
      - Launches
      parameters:
      - name: id
        in: path
        description: Unique launch identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Launch object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Launch'
        '404':
          description: Launch not found
  /launches/query:
    post:
      operationId: queryLaunches
      summary: Query Launches
      description: Query launches with MongoDB-style filters, pagination, and field population
      tags:
      - Launches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Paginated query result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
components:
  schemas:
    Failure:
      type: object
      description: Launch failure record
      properties:
        time:
          type: integer
          description: Time of failure in seconds from launch
        altitude:
          type: integer
          nullable: true
          description: Altitude at failure in kilometers
        reason:
          type: string
          description: Description of the failure cause
    QueryResult:
      type: object
      description: Paginated query result
      properties:
        docs:
          type: array
          description: Array of result documents
          items:
            type: object
        totalDocs:
          type: integer
          description: Total number of matching documents
        offset:
          type: integer
          description: Current offset
        limit:
          type: integer
          description: Results per page
        totalPages:
          type: integer
          description: Total number of pages
        page:
          type: integer
          description: Current page number
        pagingCounter:
          type: integer
          description: Index of first document in this page
        hasPrevPage:
          type: boolean
          description: Whether a previous page exists
        hasNextPage:
          type: boolean
          description: Whether a next page exists
        prevPage:
          type: integer
          nullable: true
          description: Previous page number
        nextPage:
          type: integer
          nullable: true
          description: Next page number
    CrewAssignment:
      type: object
      description: Crew member assignment for a launch
      properties:
        crew:
          type: string
          description: Crew member ID
        role:
          type: string
          description: Role aboard the mission
          example: Commander
    LaunchLinks:
      type: object
      description: Media and reference links for a launch
      properties:
        patch:
          type: object
          description: Mission patch image URLs
          properties:
            small:
              type: string
              format: uri
            large:
              type: string
              format: uri
        reddit:
          type: object
          description: Reddit community thread links
          properties:
            campaign:
              type: string
              format: uri
              nullable: true
            launch:
              type: string
              format: uri
              nullable: true
            media:
              type: string
              format: uri
              nullable: true
            recovery:
              type: string
              format: uri
              nullable: true
        flickr:
          type: object
          description: Flickr photo links
          properties:
            small:
              type: array
              items:
                type: string
                format: uri
            original:
              type: array
              items:
                type: string
                format: uri
        presskit:
          type: string
          format: uri
          nullable: true
          description: Press kit PDF URL
        webcast:
          type: string
          format: uri
          nullable: true
          description: Webcast stream URL
        youtube_id:
          type: string
          nullable: true
          description: YouTube video ID for the launch webcast
        article:
          type: string
          format: uri
          nullable: true
          description: News article link
        wikipedia:
          type: string
          format: uri
          nullable: true
          description: Wikipedia article link
    CoreDetail:
      type: object
      description: First stage booster core detail for a specific launch
      properties:
        core:
          type: string
          nullable: true
          description: Core ID
        flight:
          type: integer
          nullable: true
          description: Which flight number this is for this core
        gridfins:
          type: boolean
          nullable: true
          description: Whether grid fins were used
        legs:
          type: boolean
          nullable: true
          description: Whether landing legs were deployed
        reused:
          type: boolean
          nullable: true
          description: Whether this core was previously flown
        landing_attempt:
          type: boolean
          nullable: true
          description: Whether a landing was attempted
        landing_success:
          type: boolean
          nullable: true
          description: Whether landing succeeded
        landing_type:
          type: string
          nullable: true
          description: Landing type (ASDS, RTLS, Ocean)
          enum:
          - ASDS
          - RTLS
          - Ocean
        landpad:
          type: string
          nullable: true
          description: Landing pad ID
    Launch:
      type: object
      description: A SpaceX mission launch including all metadata, vehicle, and outcome data
      properties:
        id:
          type: string
          description: Unique launch identifier
          example: 62dd70d5202306255024d139
        name:
          type: string
          description: Mission designation
          example: Crew-5
        flight_number:
          type: integer
          description: Sequential SpaceX flight number
          example: 187
        date_utc:
          type: string
          format: date-time
          description: Launch date and time in UTC
          example: '2022-10-05T16:00:00.000Z'
        date_unix:
          type: integer
          description: Launch date as Unix timestamp
          example: 1664985600
        date_local:
          type: string
          description: Launch date and time in local timezone
          example: '2022-10-05T12:00:00-04:00'
        date_precision:
          type: string
          description: Precision of the launch date (half, quarter, year, month, day, hour)
          enum:
          - half
          - quarter
          - year
          - month
          - day
          - hour
        upcoming:
          type: boolean
          description: Whether this is a future planned launch
          example: false
        success:
          type: boolean
          nullable: true
          description: Whether the launch was successful (null if upcoming)
          example: true
        details:
          type: string
          nullable: true
          description: Mission description or notes
        rocket:
          type: string
          description: Rocket ID (reference to rockets endpoint)
          example: 5e9d0d95eda69973a809d1ec
        launchpad:
          type: string
          description: Launchpad ID (reference to launchpads endpoint)
          example: 5e9e4502f509094188566f88
        payloads:
          type: array
          description: List of payload IDs
          items:
            type: string
        capsules:
          type: array
          description: List of capsule IDs
          items:
            type: string
        crew:
          type: array
          description: Crew assignments with roles
          items:
            $ref: '#/components/schemas/CrewAssignment'
        ships:
          type: array
          description: Recovery ship IDs
          items:
            type: string
        cores:
          type: array
          description: First stage booster core details
          items:
            $ref: '#/components/schemas/CoreDetail'
        failures:
          type: array
          description: Failure details if launch was unsuccessful
          items:
            $ref: '#/components/schemas/Failure'
        links:
          $ref: '#/components/schemas/LaunchLinks'
        fairings:
          nullable: true
          $ref: '#/components/schemas/Fairings'
        net:
          type: boolean
          description: No Earlier Than flag — launch date is approximate
        window:
          type: integer
          nullable: true
          description: Launch window duration in seconds
        auto_update:
          type: boolean
          description: Whether launch data auto-syncs from external sources
        tbd:
          type: boolean
          description: To Be Determined — date or details are unconfirmed
        launch_library_id:
          type: string
          format: uuid
          nullable: true
          description: Launch Library 2 reference ID
    QueryRequest:
      type: object
      description: MongoDB-style query request for paginated, filtered lookups
      properties:
        query:
          type: object
          description: MongoDB query filter object
          additionalProperties: true
        options:
          type: object
          description: Query options for pagination and population
          properties:
            limit:
              type: integer
              description: Maximum number of results to return
            offset:
              type: integer
              description: Number of results to skip
            page:
              type: integer
              description: Page number for pagination
            populate:
              type: array
              description: Fields to populate with referenced documents
              items:
                type: string
            select:
              type: object
              description: Field projection (1 to include, 0 to exclude)
              additionalProperties:
                type: integer
            sort:
              type: object
              description: Sort specification
              additionalProperties:
                type: integer
    Fairings:
      type: object
      description: Payload fairing recovery details
      properties:
        reused:
          type: boolean
          nullable: true
        recovery_attempt:
          type: boolean
          nullable: true
        recovered:
          type: boolean
          nullable: true
        ships:
          type: array
          items:
            type: string
externalDocs:
  description: SpaceX API GitHub Repository
  url: https://github.com/r-spacex/SpaceX-API