openapi: 3.0.3
info:
  title: SpaceX REST API
  description: |
    Community-maintained, open-source REST API for SpaceX data — launches, rockets,
    capsules, cores, crew, dragons, payloads, ships, landpads, launchpads, Starlink
    satellites, the Tesla Roadster ephemeris, company info, and historical events.
    Source: https://github.com/r-spacex/SpaceX-API (Apache 2.0).

    STATUS: Maintenance-only as of 2024. New launches/missions are NOT being added.
    Existing data remains queryable; project remains hosted for historical lookups
    and as a teaching/sample API.

    Each resource is independently versioned. The Launches resource has both v4 and
    v5 surfaces; v5 omits the v4 response/query transforms (`tdb` typo retained for v4
    parity). All other resources are v4-only.

    Authentication: only required for destructive (create/update/delete) admin routes
    via the `spacex-key` header. All read operations are public.

    Querying: every resource exposes a POST `/{resource}/query` endpoint that accepts
    a mongoose-paginate-v2 body of the form `{ query: <MongoDB find()>, options: {...} }`.
  version: '4.0'
  contact:
    name: r-spacex community
    url: https://github.com/r-spacex/SpaceX-API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
  x-status: maintenance-only
servers:
  - url: https://api.spacexdata.com
    description: Canonical hosted REST endpoint (community-operated)
tags:
  - name: Capsules
    description: Detailed info for serialized Dragon capsules.
  - name: Company
    description: Detailed info about SpaceX as a company (single document).
  - name: Cores
    description: Detailed info for serialized first-stage cores.
  - name: Crew
    description: Detailed info on Dragon crew members.
  - name: Dragons
    description: Detailed info about Dragon capsule versions.
  - name: History
    description: Detailed info on SpaceX historical events.
  - name: Landpads
    description: Detailed info about landing pads and droneships.
  - name: Launches
    description: Detailed info about SpaceX launches (v4 and v5).
  - name: Launchpads
    description: Detailed info about launchpads.
  - name: Payloads
    description: Detailed info about launch payloads.
  - name: Roadster
    description: Detailed info about Elon Musk's Tesla Roadster ephemeris.
  - name: Rockets
    description: Detailed info about rocket versions.
  - name: Ships
    description: Detailed info about ships in the SpaceX fleet.
  - name: Starlink
    description: Detailed info about Starlink satellites and orbits.
security: []
paths:
  # ---------------------- CAPSULES ----------------------
  /v4/capsules:
    get:
      operationId: listCapsules
      summary: List All Capsules
      description: Return every Dragon capsule record in the dataset.
      tags: [Capsules]
      responses:
        '200':
          description: Array of capsule records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Capsule'
        '400': { $ref: '#/components/responses/BadRequest' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/capsules/{id}:
    get:
      operationId: getCapsule
      summary: Get One Capsule
      description: Return a single Dragon capsule record by its UUID.
      tags: [Capsules]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Capsule record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Capsule' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/capsules/query:
    post:
      operationId: queryCapsules
      summary: Query Capsules
      description: Run a mongoose-paginate-v2 query against the capsule collection.
      tags: [Capsules]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated capsule result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCapsules'
        '400': { $ref: '#/components/responses/BadRequest' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- COMPANY ----------------------
  /v4/company:
    get:
      operationId: getCompany
      summary: Get Company Info
      description: Return the single SpaceX company-info document.
      tags: [Company]
      responses:
        '200':
          description: SpaceX company document.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Company' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- CORES ----------------------
  /v4/cores:
    get:
      operationId: listCores
      summary: List All Cores
      description: Return every first-stage core record in the dataset.
      tags: [Cores]
      responses:
        '200':
          description: Array of core records.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Core' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/cores/{id}:
    get:
      operationId: getCore
      summary: Get One Core
      description: Return a single first-stage core record by its UUID.
      tags: [Cores]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Core record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Core' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/cores/query:
    post:
      operationId: queryCores
      summary: Query Cores
      description: Run a mongoose-paginate-v2 query against the core collection.
      tags: [Cores]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated core result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedCores' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- CREW ----------------------
  /v4/crew:
    get:
      operationId: listCrew
      summary: List All Crew
      description: Return every Dragon crew member record.
      tags: [Crew]
      responses:
        '200':
          description: Array of crew member records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/CrewMember' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/crew/{id}:
    get:
      operationId: getCrewMember
      summary: Get One Crew Member
      description: Return a single crew member record by its UUID.
      tags: [Crew]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Crew member record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CrewMember' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/crew/query:
    post:
      operationId: queryCrew
      summary: Query Crew
      description: Run a mongoose-paginate-v2 query against the crew collection.
      tags: [Crew]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated crew result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedCrew' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- DRAGONS ----------------------
  /v4/dragons:
    get:
      operationId: listDragons
      summary: List All Dragon Versions
      description: Return every Dragon capsule version record (Dragon 1, Dragon 2, etc.).
      tags: [Dragons]
      responses:
        '200':
          description: Array of Dragon version records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Dragon' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/dragons/{id}:
    get:
      operationId: getDragon
      summary: Get One Dragon Version
      description: Return a single Dragon version record by its UUID.
      tags: [Dragons]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Dragon version record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Dragon' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/dragons/query:
    post:
      operationId: queryDragons
      summary: Query Dragons
      description: Run a mongoose-paginate-v2 query against the dragons collection.
      tags: [Dragons]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated dragon result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedDragons' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- HISTORY ----------------------
  /v4/history:
    get:
      operationId: listHistoryEvents
      summary: List All History Events
      description: Return every SpaceX historical event record.
      tags: [History]
      responses:
        '200':
          description: Array of history event records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/HistoryEvent' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/history/{id}:
    get:
      operationId: getHistoryEvent
      summary: Get One History Event
      description: Return a single SpaceX history event by its UUID.
      tags: [History]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: History event record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HistoryEvent' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/history/query:
    post:
      operationId: queryHistoryEvents
      summary: Query History Events
      description: Run a mongoose-paginate-v2 query against the history collection.
      tags: [History]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated history result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedHistory' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- LANDPADS ----------------------
  /v4/landpads:
    get:
      operationId: listLandpads
      summary: List All Landing Pads
      description: Return every landing pad / droneship record.
      tags: [Landpads]
      responses:
        '200':
          description: Array of landing pad records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Landpad' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/landpads/{id}:
    get:
      operationId: getLandpad
      summary: Get One Landing Pad
      description: Return a single landing pad by its UUID.
      tags: [Landpads]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Landing pad record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Landpad' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/landpads/query:
    post:
      operationId: queryLandpads
      summary: Query Landing Pads
      description: Run a mongoose-paginate-v2 query against the landpads collection.
      tags: [Landpads]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated landpad result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedLandpads' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- LAUNCHES (v5 canonical, v4 retained) ----------------------
  /v5/launches:
    get:
      operationId: listLaunchesV5
      summary: List All Launches
      description: Return every launch record sorted ascending by flight_number.
      tags: [Launches]
      responses:
        '200':
          description: Array of launch records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Launch' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v5/launches/past:
    get:
      operationId: listPastLaunches
      summary: List Past Launches
      description: 'Return all launches with `upcoming: false`.'
      tags: [Launches]
      responses:
        '200':
          description: Array of past launch records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Launch' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v5/launches/upcoming:
    get:
      operationId: listUpcomingLaunches
      summary: List Upcoming Launches
      description: 'Return all launches with `upcoming: true`. In maintenance-only mode this list is no longer updated.'
      tags: [Launches]
      responses:
        '200':
          description: Array of upcoming launch records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Launch' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v5/launches/latest:
    get:
      operationId: getLatestLaunch
      summary: Get Latest Launch
      description: 'Return the most recent past launch (highest flight_number with `upcoming: false`).'
      tags: [Launches]
      responses:
        '200':
          description: Latest launch record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Launch' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v5/launches/next:
    get:
      operationId: getNextLaunch
      summary: Get Next Launch
      description: 'Return the next upcoming launch (lowest flight_number with `upcoming: true`).'
      tags: [Launches]
      responses:
        '200':
          description: Next launch record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Launch' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v5/launches/{id}:
    get:
      operationId: getLaunch
      summary: Get One Launch
      description: Return a single launch by its UUID.
      tags: [Launches]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Launch record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Launch' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v5/launches/query:
    post:
      operationId: queryLaunches
      summary: Query Launches
      description: Run a mongoose-paginate-v2 query against the launches collection with optional populate.
      tags: [Launches]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated launch result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedLaunches' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- LAUNCHPADS ----------------------
  /v4/launchpads:
    get:
      operationId: listLaunchpads
      summary: List All Launchpads
      description: Return every launchpad record.
      tags: [Launchpads]
      responses:
        '200':
          description: Array of launchpad records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Launchpad' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/launchpads/{id}:
    get:
      operationId: getLaunchpad
      summary: Get One Launchpad
      description: Return a single launchpad by its UUID.
      tags: [Launchpads]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Launchpad record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Launchpad' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/launchpads/query:
    post:
      operationId: queryLaunchpads
      summary: Query Launchpads
      description: Run a mongoose-paginate-v2 query against the launchpads collection.
      tags: [Launchpads]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated launchpad result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedLaunchpads' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- PAYLOADS ----------------------
  /v4/payloads:
    get:
      operationId: listPayloads
      summary: List All Payloads
      description: Return every payload record.
      tags: [Payloads]
      responses:
        '200':
          description: Array of payload records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Payload' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/payloads/{id}:
    get:
      operationId: getPayload
      summary: Get One Payload
      description: Return a single payload by its UUID.
      tags: [Payloads]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Payload record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Payload' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/payloads/query:
    post:
      operationId: queryPayloads
      summary: Query Payloads
      description: Run a mongoose-paginate-v2 query against the payloads collection.
      tags: [Payloads]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated payload result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedPayloads' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- ROADSTER ----------------------
  /v4/roadster:
    get:
      operationId: getRoadster
      summary: Get Roadster Ephemeris
      description: Return the current orbital ephemeris for Elon Musk's Tesla Roadster.
      tags: [Roadster]
      responses:
        '200':
          description: Roadster ephemeris record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Roadster' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/roadster/query:
    post:
      operationId: queryRoadster
      summary: Query Roadster
      description: Run a mongoose-paginate-v2 query against the roadster collection (single document).
      tags: [Roadster]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated roadster result.
          content:
            application/json:
              schema:
                type: object
                description: Paginated roadster wrapper (single document).
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- ROCKETS ----------------------
  /v4/rockets:
    get:
      operationId: listRockets
      summary: List All Rockets
      description: Return every rocket version record.
      tags: [Rockets]
      responses:
        '200':
          description: Array of rocket records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Rocket' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/rockets/{id}:
    get:
      operationId: getRocket
      summary: Get One Rocket
      description: Return a single rocket by its UUID.
      tags: [Rockets]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Rocket record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Rocket' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/rockets/query:
    post:
      operationId: queryRockets
      summary: Query Rockets
      description: Run a mongoose-paginate-v2 query against the rockets collection.
      tags: [Rockets]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated rocket result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedRockets' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- SHIPS ----------------------
  /v4/ships:
    get:
      operationId: listShips
      summary: List All Ships
      description: Return every ship in the SpaceX fleet (droneships, recovery ships, support).
      tags: [Ships]
      responses:
        '200':
          description: Array of ship records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Ship' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/ships/{id}:
    get:
      operationId: getShip
      summary: Get One Ship
      description: Return a single ship by its UUID.
      tags: [Ships]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Ship record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Ship' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/ships/query:
    post:
      operationId: queryShips
      summary: Query Ships
      description: Run a mongoose-paginate-v2 query against the ships collection.
      tags: [Ships]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated ship result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedShips' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  # ---------------------- STARLINK ----------------------
  /v4/starlink:
    get:
      operationId: listStarlinkSatellites
      summary: List All Starlink Satellites
      description: Return every Starlink satellite record with raw Space-Track orbit data.
      tags: [Starlink]
      responses:
        '200':
          description: Array of Starlink satellite records.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/StarlinkSat' } }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/starlink/{id}:
    get:
      operationId: getStarlinkSatellite
      summary: Get One Starlink Satellite
      description: Return a single Starlink satellite by its UUID.
      tags: [Starlink]
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Starlink satellite record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StarlinkSat' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v4/starlink/query:
    post:
      operationId: queryStarlinkSatellites
      summary: Query Starlink Satellites
      description: Run a mongoose-paginate-v2 query against the starlink collection.
      tags: [Starlink]
      requestBody: { $ref: '#/components/requestBodies/QueryBody' }
      responses:
        '200':
          description: Paginated starlink result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginatedStarlink' }
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    SpacexKey:
      type: apiKey
      in: header
      name: spacex-key
      description: |
        Admin API key for destructive (create/update/delete) operations.
        Not required for any read endpoint.
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      description: Resource UUID (MongoDB ObjectId, e.g. `5e9d0d95eda69973a809d1ec`).
      schema:
        type: string
        pattern: '^[a-f0-9]{24}$'
  requestBodies:
    QueryBody:
      description: mongoose-paginate-v2 query body.
      required: false
      content:
        application/json:
          schema: { $ref: '#/components/schemas/QueryRequest' }
          example:
            query: {}
            options:
              limit: 10
              page: 1
  responses:
    BadRequest:
      description: Bad request — query body invalid or operation rejected.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing or invalid `spacex-key` header (admin routes only).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        message: { type: string, description: Human-readable error message. }
        status: { type: integer, description: HTTP status code echoed in body. }
    QueryRequest:
      type: object
      description: mongoose-paginate-v2 query body.
      properties:
        query:
          type: object
          description: MongoDB find() filter document.
          additionalProperties: true
        options:
          type: object
          description: Pagination + projection options.
          properties:
            select: { description: 'Fields to include/exclude (string or object).', oneOf: [{type: string}, {type: object}] }
            sort: { description: 'Sort order (string or object).', oneOf: [{type: string}, {type: object}] }
            offset: { type: integer }
            page: { type: integer }
            limit: { type: integer }
            pagination: { type: boolean }
            populate: { description: 'Populate definitions (array, object, or string).', oneOf: [{type: array, items: {}}, {type: object}, {type: string}] }
    PaginationEnvelope:
      type: object
      description: Default mongoose-paginate-v2 wrapper.
      properties:
        totalDocs: { type: integer }
        offset: { type: integer }
        limit: { type: integer }
        totalPages: { type: integer }
        page: { type: integer }
        pagingCounter: { type: integer }
        hasPrevPage: { type: boolean }
        hasNextPage: { type: boolean }
        prevPage: { type: integer, nullable: true }
        nextPage: { type: integer, nullable: true }
    PaginatedCapsules:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Capsule' } }
    PaginatedCores:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Core' } }
    PaginatedCrew:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/CrewMember' } }
    PaginatedDragons:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Dragon' } }
    PaginatedHistory:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/HistoryEvent' } }
    PaginatedLandpads:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Landpad' } }
    PaginatedLaunches:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Launch' } }
    PaginatedLaunchpads:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Launchpad' } }
    PaginatedPayloads:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Payload' } }
    PaginatedRockets:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Rocket' } }
    PaginatedShips:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/Ship' } }
    PaginatedStarlink:
      allOf:
        - $ref: '#/components/schemas/PaginationEnvelope'
        - type: object
          properties:
            docs: { type: array, items: { $ref: '#/components/schemas/StarlinkSat' } }

    # ---- Resource schemas ----
    Capsule:
      type: object
      description: A serialized Dragon capsule.
      properties:
        id: { type: string, description: UUID. }
        serial: { type: string, description: 'Capsule serial (e.g. C112).' }
        status:
          type: string
          enum: [unknown, active, retired, destroyed]
          description: Operational status.
        type:
          type: string
          enum: ['Dragon 1.0', 'Dragon 1.1', 'Dragon 2.0']
          description: Capsule type / generation.
        dragon: { type: string, nullable: true, description: Dragon version UUID. }
        reuse_count: { type: integer, default: 0 }
        water_landings: { type: integer, default: 0 }
        land_landings: { type: integer, default: 0 }
        last_update: { type: string, nullable: true, description: Free-form latest status note. }
        launches: { type: array, items: { type: string }, description: UUIDs of launches this capsule has flown. }
      required: [serial, status, type]
    Core:
      type: object
      description: A serialized Falcon first-stage core.
      properties:
        id: { type: string }
        serial: { type: string, description: 'Booster serial (e.g. B1062).' }
        block: { type: integer, nullable: true }
        status:
          type: string
          enum: [active, inactive, unknown, expended, lost, retired]
        reuse_count: { type: integer, default: 0 }
        rtls_attempts: { type: integer, default: 0 }
        rtls_landings: { type: integer, default: 0 }
        asds_attempts: { type: integer, default: 0 }
        asds_landings: { type: integer, default: 0 }
        last_update: { type: string, nullable: true }
        launches: { type: array, items: { type: string } }
      required: [serial, status]
    CrewMember:
      type: object
      description: A SpaceX Dragon crew member.
      properties:
        id: { type: string }
        name: { type: string, nullable: true }
        status:
          type: string
          enum: [active, inactive, retired, unknown]
        agency: { type: string, nullable: true, description: 'e.g. NASA, ESA.' }
        image: { type: string, nullable: true, format: uri }
        wikipedia: { type: string, nullable: true, format: uri }
        launches: { type: array, items: { type: string } }
      required: [status]
    Dragon:
      type: object
      description: A Dragon capsule version (Dragon 1, Dragon 2, etc.).
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string }
        active: { type: boolean }
        crew_capacity: { type: integer }
        sidewall_angle_deg: { type: number }
        orbit_duration_yr: { type: number }
        dry_mass_kg: { type: number }
        dry_mass_lb: { type: number }
        first_flight: { type: string, nullable: true }
        heat_shield:
          type: object
          properties:
            material: { type: string }
            size_meters: { type: number }
            temp_degrees: { type: number }
            dev_partner: { type: string }
        thrusters:
          type: array
          description: Array of thruster groups.
          items: { type: object, additionalProperties: true }
        launch_payload_mass: { $ref: '#/components/schemas/KgLb' }
        launch_payload_vol: { $ref: '#/components/schemas/CubicMetersFeet' }
        return_payload_mass: { $ref: '#/components/schemas/KgLb' }
        return_payload_vol: { $ref: '#/components/schemas/CubicMetersFeet' }
        pressurized_capsule:
          type: object
          properties:
            payload_volume: { $ref: '#/components/schemas/CubicMetersFeet' }
        trunk:
          type: object
          properties:
            trunk_volume: { $ref: '#/components/schemas/CubicMetersFeet' }
            cargo:
              type: object
              properties:
                solar_array: { type: integer }
                unpressurized_cargo: { type: boolean }
        height_w_trunk: { $ref: '#/components/schemas/MetersFeet' }
        diameter: { $ref: '#/components/schemas/MetersFeet' }
        flickr_images: { type: array, items: { type: string, format: uri } }
        wikipedia: { type: string, format: uri }
        description: { type: string }
      required: [name, type, active, crew_capacity]
    HistoryEvent:
      type: object
      description: A historical SpaceX event.
      properties:
        id: { type: string }
        title: { type: string, nullable: true }
        event_date_utc: { type: string, nullable: true, format: date-time }
        event_date_unix: { type: integer, nullable: true }
        details: { type: string, nullable: true }
        links:
          type: object
          properties:
            article: { type: string, nullable: true, format: uri }
    Landpad:
      type: object
      description: A SpaceX landing pad or droneship.
      properties:
        id: { type: string }
        name: { type: string, nullable: true }
        full_name: { type: string, nullable: true }
        status:
          type: string
          enum: [active, inactive, unknown, retired, lost, under construction]
        type: { type: string, nullable: true, description: 'e.g. RTLS, ASDS.' }
        locality: { type: string, nullable: true }
        region: { type: string, nullable: true }
        latitude: { type: number, nullable: true }
        longitude: { type: number, nullable: true }
        landing_attempts: { type: integer, default: 0 }
        landing_successes: { type: integer, default: 0 }
        wikipedia: { type: string, nullable: true, format: uri }
        details: { type: string, nullable: true }
        launches: { type: array, items: { type: string } }
      required: [status]
    Launchpad:
      type: object
      description: A SpaceX launch pad.
      properties:
        id: { type: string }
        name: { type: string, nullable: true }
        full_name: { type: string, nullable: true }
        status:
          type: string
          enum: [active, inactive, unknown, retired, lost, under construction]
        locality: { type: string, nullable: true }
        region: { type: string, nullable: true }
        timezone: { type: string, nullable: true }
        latitude: { type: number, nullable: true }
        longitude: { type: number, nullable: true }
        launch_attempts: { type: integer, default: 0 }
        launch_successes: { type: integer, default: 0 }
        rockets: { type: array, items: { type: string } }
        launches: { type: array, items: { type: string } }
      required: [status]
    Launch:
      type: object
      description: A SpaceX launch record.
      properties:
        id: { type: string }
        flight_number: { type: integer }
        name: { type: string }
        date_utc: { type: string, format: date-time }
        date_unix: { type: integer }
        date_local: { type: string }
        date_precision:
          type: string
          enum: [half, quarter, year, month, day, hour]
        static_fire_date_utc: { type: string, nullable: true, format: date-time }
        static_fire_date_unix: { type: integer, nullable: true }
        tbd: { type: boolean, default: false }
        net: { type: boolean, default: false }
        window: { type: integer, nullable: true }
        rocket: { type: string, nullable: true }
        success: { type: boolean, nullable: true }
        failures:
          type: array
          items:
            type: object
            properties:
              time: { type: integer }
              altitude: { type: integer, nullable: true }
              reason: { type: string }
        upcoming: { type: boolean }
        details: { type: string, nullable: true }
        fairings:
          type: object
          nullable: true
          properties:
            reused: { type: boolean, nullable: true }
            recovery_attempt: { type: boolean, nullable: true }
            recovered: { type: boolean, nullable: true }
            ships: { type: array, items: { type: string } }
        crew:
          type: array
          items:
            type: object
            properties:
              crew: { type: string, nullable: true }
              role: { type: string, nullable: true }
        ships: { type: array, items: { type: string } }
        capsules: { type: array, items: { type: string } }
        payloads: { type: array, items: { type: string } }
        launchpad: { type: string, nullable: true }
        cores:
          type: array
          items:
            type: object
            properties:
              core: { type: string, nullable: true }
              flight: { type: integer, nullable: true }
              gridfins: { type: boolean, nullable: true }
              legs: { type: boolean, nullable: true }
              reused: { type: boolean, nullable: true }
              landing_attempt: { type: boolean, nullable: true }
              landing_success: { type: boolean, nullable: true }
              landing_type: { type: string, nullable: true }
              landpad: { type: string, nullable: true }
        links:
          type: object
          properties:
            patch:
              type: object
              properties:
                small: { type: string, nullable: true, format: uri }
                large: { type: string, nullable: true, format: uri }
            reddit:
              type: object
              properties:
                campaign: { type: string, nullable: true, format: uri }
                launch: { type: string, nullable: true, format: uri }
                media: { type: string, nullable: true, format: uri }
                recovery: { type: string, nullable: true, format: uri }
            flickr:
              type: object
              properties:
                small: { type: array, items: { type: string, format: uri } }
                original: { type: array, items: { type: string, format: uri } }
            presskit: { type: string, nullable: true, format: uri }
            webcast: { type: string, nullable: true, format: uri }
            youtube_id: { type: string, nullable: true }
            article: { type: string, nullable: true, format: uri }
            wikipedia: { type: string, nullable: true, format: uri }
        auto_update: { type: boolean, default: true }
      required: [flight_number, name, date_utc, date_unix, date_local, date_precision, upcoming]
    Payload:
      type: object
      description: A launch payload.
      properties:
        id: { type: string }
        name: { type: string, nullable: true }
        type: { type: string, nullable: true }
        reused: { type: boolean, default: false }
        launch: { type: string, nullable: true }
        customers: { type: array, items: { type: string } }
        norad_ids: { type: array, items: { type: integer } }
        nationalities: { type: array, items: { type: string } }
        manufacturers: { type: array, items: { type: string } }
        mass_kg: { type: number, nullable: true }
        mass_lbs: { type: number, nullable: true }
        orbit: { type: string, nullable: true }
        reference_system: { type: string, nullable: true }
        regime: { type: string, nullable: true }
        longitude: { type: number, nullable: true }
        semi_major_axis_km: { type: number, nullable: true }
        eccentricity: { type: number, nullable: true }
        periapsis_km: { type: number, nullable: true }
        apoapsis_km: { type: number, nullable: true }
        inclination_deg: { type: number, nullable: true }
        period_min: { type: number, nullable: true }
        lifespan_years: { type: number, nullable: true }
        epoch: { type: string, nullable: true, format: date-time }
        mean_motion: { type: number, nullable: true }
        raan: { type: number, nullable: true }
        arg_of_pericenter: { type: number, nullable: true }
        mean_anomaly: { type: number, nullable: true }
        dragon:
          type: object
          nullable: true
          properties:
            capsule: { type: string, nullable: true }
            mass_returned_kg: { type: number, nullable: true }
            mass_returned_lbs: { type: number, nullable: true }
            flight_time_sec: { type: integer, nullable: true }
            manifest: { type: string, nullable: true }
            water_landing: { type: boolean, nullable: true }
            land_landing: { type: boolean, nullable: true }
    Roadster:
      type: object
      description: Tesla Roadster ephemeris (single document).
      properties:
        id: { type: string }
        name: { type: string }
        launch_date_utc: { type: string, format: date-time }
        launch_date_unix: { type: integer }
        launch_mass_kg: { type: number }
        launch_mass_lbs: { type: number }
        norad_id: { type: integer }
        epoch_jd: { type: number }
        orbit_type: { type: string }
        apoapsis_au: { type: number }
        periapsis_au: { type: number }
        semi_major_axis_au: { type: number }
        eccentricity: { type: number }
        inclination: { type: number }
        longitude: { type: number }
        periapsis_arg: { type: number }
        period_days: { type: number }
        speed_kph: { type: number }
        speed_mph: { type: number }
        earth_distance_km: { type: number }
        earth_distance_mi: { type: number }
        mars_distance_km: { type: number }
        mars_distance_mi: { type: number }
        flickr_images: { type: array, items: { type: string, format: uri } }
        wikipedia: { type: string, format: uri }
        video: { type: string, format: uri }
        details: { type: string }
    Rocket:
      type: object
      description: A rocket version (Falcon 1, Falcon 9, Falcon Heavy, Starship).
      properties:
        id: { type: string }
        name: { type: string }
        type: { type: string }
        active: { type: boolean }
        stages: { type: integer }
        boosters: { type: integer }
        cost_per_launch: { type: number, description: USD per launch. }
        success_rate_pct: { type: number }
        first_flight: { type: string, format: date }
        country: { type: string }
        company: { type: string }
        height: { $ref: '#/components/schemas/MetersFeet' }
        diameter: { $ref: '#/components/schemas/MetersFeet' }
        mass: { $ref: '#/components/schemas/KgLb' }
        payload_weights:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              name: { type: string }
              kg: { type: number }
              lb: { type: number }
        first_stage:
          type: object
          properties:
            reusable: { type: boolean }
            engines: { type: integer }
            fuel_amount_tons: { type: number }
            burn_time_sec: { type: number, nullable: true }
            thrust_sea_level: { $ref: '#/components/schemas/Thrust' }
            thrust_vacuum: { $ref: '#/components/schemas/Thrust' }
        second_stage:
          type: object
          properties:
            reusable: { type: boolean }
            engines: { type: integer }
            fuel_amount_tons: { type: number }
            burn_time_sec: { type: number, nullable: true }
            thrust: { $ref: '#/components/schemas/Thrust' }
            payloads:
              type: object
              additionalProperties: true
        engines:
          type: object
          additionalProperties: true
        landing_legs:
          type: object
          properties:
            number: { type: integer }
            material: { type: string, nullable: true }
        flickr_images: { type: array, items: { type: string, format: uri } }
        wikipedia: { type: string, format: uri }
        description: { type: string }
    Ship:
      type: object
      description: A ship in the SpaceX fleet (droneship, recovery, support).
      properties:
        id: { type: string }
        name: { type: string }
        legacy_id: { type: string, nullable: true }
        model: { type: string, nullable: true }
        type: { type: string, nullable: true }
        roles: { type: array, items: { type: string } }
        active: { type: boolean }
        imo: { type: integer, nullable: true }
        mmsi: { type: integer, nullable: true }
        abs: { type: integer, nullable: true }
        class: { type: integer, nullable: true }
        mass_kg: { type: number, nullable: true }
        mass_lbs: { type: number, nullable: true }
        year_built: { type: integer, nullable: true }
        home_port: { type: string, nullable: true }
        status: { type: string, nullable: true }
        speed_kn: { type: number, nullable: true }
        course_deg: { type: number, nullable: true }
        latitude: { type: number, nullable: true }
        longitude: { type: number, nullable: true }
        last_ais_update: { type: string, nullable: true, format: date-time }
        link: { type: string, nullable: true, format: uri }
        image: { type: string, nullable: true, format: uri }
        launches: { type: array, items: { type: string } }
      required: [name, active]
    StarlinkSat:
      type: object
      description: A Starlink satellite with Space-Track OMM orbit data.
      properties:
        id: { type: string }
        version: { type: string, nullable: true }
        launch: { type: string, nullable: true, description: Launch UUID. }
        longitude: { type: number, nullable: true }
        latitude: { type: number, nullable: true }
        height_km: { type: number, nullable: true }
        velocity_kms: { type: number, nullable: true }
        spaceTrack:
          type: object
          description: Raw Space-Track Orbit Mean Elements Message fields.
          additionalProperties: true
    Company:
      type: object
      description: SpaceX company info document (single).
      properties:
        id: { type: string }
        name: { type: string }
        founder: { type: string }
        founded: { type: integer }
        employees: { type: integer }
        vehicles: { type: integer }
        launch_sites: { type: integer }
        test_sites: { type: integer }
        ceo: { type: string }
        cto: { type: string }
        coo: { type: string }
        cto_propulsion: { type: string }
        valuation: { type: number }
        headquarters:
          type: object
          properties:
            address: { type: string }
            city: { type: string }
            state: { type: string }
        links:
          type: object
          properties:
            website: { type: string, format: uri }
            flickr: { type: string, format: uri }
            twitter: { type: string, format: uri }
            elon_twitter: { type: string, format: uri }
        summary: { type: string }
    MetersFeet:
      type: object
      properties:
        meters: { type: number, nullable: true }
        feet: { type: number, nullable: true }
    KgLb:
      type: object
      properties:
        kg: { type: number, nullable: true }
        lb: { type: number, nullable: true }
    CubicMetersFeet:
      type: object
      properties:
        cubic_meters: { type: number, nullable: true }
        cubic_feet: { type: number, nullable: true }
    Thrust:
      type: object
      properties:
        kN: { type: number, nullable: true }
        lbf: { type: number, nullable: true }