LeoLabs Platform API

openapi: 3.0.3
info:
  title: LeoLabs Platform API
  version: v1
  description: |
    The LeoLabs Platform API provides programmatic access to LeoLabs' commercial low Earth orbit (LEO)
    catalog: tracked space objects, radar measurements, orbital state vectors, TLEs, ephemeris propagation,
    planned passes, and radar instrument tasking.

    PROVENANCE: this description was DERIVED from LeoLabs' own published Python client
    (PyPI package `leolabs` 0.1.22, authored by "LeoLabs, Inc.", modules `leolabs/cli/commands.py`
    and `leolabs/cli/utils.py`) plus the request/response examples in that package's README.
    It is NOT an official LeoLabs OpenAPI document — LeoLabs' reference documentation
    (https://docs.leolabs.space/) is behind a customer login, so the authoritative contract could not be
    retrieved. Paths, methods, parameter names, the authorization header format and the response field
    names below all come verbatim from that first-party source. Nothing was invented; where the source
    did not reveal a type or a field it is simply absent here. The client was last published 2018-11-06,
    so this reflects the v1 surface as of that release and may be incomplete relative to today's API.
  contact:
    name: LeoLabs Support
    email: support@leolabs.space
    url: https://www.leolabs.space/
  x-provenance:
    method: derived
    generated: '2026-07-19'
    source: https://pypi.org/project/leolabs/0.1.22/
servers:
  - url: https://api.leolabs.space/v1
    description: LeoLabs Platform API production
security:
  - leolabsKeyPair: []
tags:
  - name: catalog
    description: LeoLabs catalog of tracked LEO objects, their measurements, states and propagations.
  - name: instruments
    description: LeoLabs radar instruments and their tasking.
paths:
  /catalog/objects:
    get:
      tags: [catalog]
      operationId: listCatalogObjects
      summary: List catalog objects
      description: Lists the objects in the LeoLabs catalog.
      responses:
        '200':
          description: A list of catalog objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/search:
    get:
      tags: [catalog]
      operationId: searchCatalogObjects
      summary: Search the catalog by NORAD catalog number
      description: Resolves a NORAD catalog number to a LeoLabs catalog object.
      parameters:
        - name: noradCatalogNumber
          in: query
          required: true
          description: The NORAD catalog number of the object, e.g. 27386 for ENVISAT.
          schema:
            type: integer
      responses:
        '200':
          description: The matching catalog object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
    get:
      tags: [catalog]
      operationId: getCatalogObject
      summary: Get a catalog object
      description: Retrieves a single catalog object by its LeoLabs catalog number.
      responses:
        '200':
          description: The catalog object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogObject'
              example:
                name: ENVISAT
                noradCatalogNumber: 27386
                catalogNumber: L335
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/measurements:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
    get:
      tags: [catalog]
      operationId: listCatalogObjectMeasurements
      summary: List radar measurements for a catalog object
      description: Returns the radar measurements collected for a catalog object over a time span.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
      responses:
        '200':
          description: The measurements for the object over the requested time span.
          content:
            application/json:
              schema:
                type: object
                properties:
                  measurements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Measurement'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/tasks:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
    post:
      tags: [catalog]
      operationId: createCatalogObjectTask
      summary: Request priority tasking for a catalog object
      description: Requests that the radar network prioritise tracking of this object over a time span.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [startTime, endTime]
              properties:
                startTime:
                  type: string
                  format: date-time
                endTime:
                  type: string
                  format: date-time
                priority:
                  type: integer
                  description: Tasking priority. The LeoLabs client sends 100.
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskRef'
              example:
                id: 27102
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/passes/planned:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
    get:
      tags: [catalog]
      operationId: listCatalogObjectPlannedPasses
      summary: List planned passes for a catalog object
      description: |
        Returns the planned radar passes for a catalog object. The LeoLabs client passes the literal
        value `all` as the catalog number to request planned passes across the whole catalog.
      responses:
        '200':
          description: Planned passes.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/statistics:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
    get:
      tags: [catalog]
      operationId: getCatalogObjectStatistics
      summary: Get statistics for a catalog object
      description: |
        Returns tracking statistics for a catalog object. The LeoLabs client passes the literal value
        `all` as the catalog number to request catalog-wide statistics.
      responses:
        '200':
          description: Statistics.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/states:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
    get:
      tags: [catalog]
      operationId: listCatalogObjectStates
      summary: List orbital state vectors for a catalog object
      description: |
        Returns orbital state vectors for a catalog object, either over a time span
        (`startTime`/`endTime`) or the most recent state (`latest=1`).
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - name: latest
          in: query
          required: false
          description: Set to 1 to return only the most recent state vector.
          schema:
            type: integer
      responses:
        '200':
          description: State vectors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  states:
                    type: array
                    items:
                      $ref: '#/components/schemas/State'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/states/{stateId}:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
      - $ref: '#/components/parameters/StateId'
    get:
      tags: [catalog]
      operationId: getCatalogObjectState
      summary: Get an orbital state vector
      description: Retrieves a single orbital state vector by id.
      responses:
        '200':
          description: The state vector.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/State'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/states/{stateId}/tles:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
      - $ref: '#/components/parameters/StateId'
    get:
      tags: [catalog]
      operationId: listCatalogObjectStateTles
      summary: List TLEs associated with a state vector
      description: Returns the two-line element sets derived from a given orbital state vector.
      responses:
        '200':
          description: TLEs for the state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tle'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/objects/{catalogNumber}/states/{stateId}/propagations:
    parameters:
      - $ref: '#/components/parameters/CatalogNumber'
      - $ref: '#/components/parameters/StateId'
    get:
      tags: [catalog]
      operationId: getCatalogObjectStatePropagation
      summary: Propagate ephemeris from a state vector
      description: |
        Propagates the orbit forward or backward from a given state vector and returns positions,
        velocities and covariances at a fixed timestep. LeoLabs documents support for propagation up to
        plus or minus 7 days from the state timestamp.
      parameters:
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - name: timestep
          in: query
          required: false
          description: Propagation timestep in seconds.
          schema:
            type: number
      responses:
        '200':
          description: The propagation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Propagation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instruments:
    get:
      tags: [instruments]
      operationId: listInstruments
      summary: List radar instruments
      description: Lists the LeoLabs radar instruments and their siting and transmit characteristics.
      responses:
        '200':
          description: The instruments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instruments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Instrument'
              example:
                instruments:
                  - id: pfisr
                    altitude: 213.0
                    longitude: -147.47104
                    latitude: 65.12992
                    transmitFrequency: 450000000.0
                    transmitPower: 2000000.0
                  - id: msr
                    altitude: 855.0
                    longitude: -103.233245
                    latitude: 31.9643
                    transmitFrequency: 440000000.0
                    transmitPower: 65000.0
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instruments/{instrumentId}:
    parameters:
      - $ref: '#/components/parameters/InstrumentId'
    get:
      tags: [instruments]
      operationId: getInstrument
      summary: Get a radar instrument
      responses:
        '200':
          description: The instrument.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instrument'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instruments/{instrumentId}/statistics:
    parameters:
      - $ref: '#/components/parameters/InstrumentId'
    get:
      tags: [instruments]
      operationId: getInstrumentStatistics
      summary: Get statistics for a radar instrument
      description: |
        Returns statistics for a radar instrument. The LeoLabs client passes the literal value `all`
        as the instrument id to request statistics across all instruments.
      responses:
        '200':
          description: Statistics.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instruments/{instrumentId}/tasks:
    parameters:
      - $ref: '#/components/parameters/InstrumentId'
    get:
      tags: [instruments]
      operationId: listInstrumentTasks
      summary: List tasks for a radar instrument
      responses:
        '200':
          description: The tasks.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags: [instruments]
      operationId: createInstrumentTask
      summary: Create a task on a radar instrument
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [startTime, endTime]
              properties:
                startTime:
                  type: string
                  format: date-time
                endTime:
                  type: string
                  format: date-time
      responses:
        '200':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskRef'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instruments/{instrumentId}/tasks/{taskId}:
    parameters:
      - $ref: '#/components/parameters/InstrumentId'
      - $ref: '#/components/parameters/TaskId'
    get:
      tags: [instruments]
      operationId: getInstrumentTask
      summary: Get a radar instrument task
      responses:
        '200':
          description: The task.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /instruments/{instrumentId}/tasks/{taskId}/measurements:
    parameters:
      - $ref: '#/components/parameters/InstrumentId'
      - $ref: '#/components/parameters/TaskId'
    get:
      tags: [instruments]
      operationId: listInstrumentTaskMeasurements
      summary: List measurements collected by a task
      responses:
        '200':
          description: The measurements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  measurements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Measurement'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    leolabsKeyPair:
      type: apiKey
      in: header
      name: Authorization
      description: |
        LeoLabs access key / secret key pair, sent as `Authorization: basic <accessKey>:<secretKey>`.
        Despite the `basic` prefix this is not RFC 7617 HTTP Basic — the LeoLabs client sends the two
        keys colon-joined and unencoded. Keys are issued from the LeoLabs Platform
        (https://platform.leolabs.space/) and the official client reads them from the
        `LEOLABS_ACCESS_KEY` and `LEOLABS_SECRET_KEY` environment variables or from `~/.leolabs/config`.
  parameters:
    CatalogNumber:
      name: catalogNumber
      in: path
      required: true
      description: LeoLabs catalog number, e.g. `L335`. Some endpoints accept the literal `all`.
      schema:
        type: string
    StateId:
      name: stateId
      in: path
      required: true
      description: Orbital state vector id.
      schema:
        type: string
    InstrumentId:
      name: instrumentId
      in: path
      required: true
      description: Radar instrument id, e.g. `pfisr` or `msr`. Some endpoints accept the literal `all`.
      schema:
        type: string
    TaskId:
      name: taskId
      in: path
      required: true
      description: Task id.
      schema:
        type: string
    StartTime:
      name: startTime
      in: query
      required: false
      description: ISO 8601 UTC start of the requested time span, e.g. `2017-11-08T00:00:00Z`.
      schema:
        type: string
        format: date-time
    EndTime:
      name: endTime
      in: query
      required: false
      description: ISO 8601 UTC end of the requested time span.
      schema:
        type: string
        format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid LeoLabs access key / secret key pair.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CatalogObject:
      type: object
      description: An object tracked in the LeoLabs LEO catalog.
      properties:
        catalogNumber:
          type: string
          description: LeoLabs catalog number, e.g. `L335`.
        noradCatalogNumber:
          type: integer
          description: NORAD catalog number, e.g. 27386.
        name:
          type: string
          description: Object name, e.g. `ENVISAT`.
    Instrument:
      type: object
      description: A LeoLabs radar instrument.
      properties:
        id:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        altitude:
          type: number
        transmitFrequency:
          type: number
        transmitPower:
          type: number
    Measurement:
      type: object
      description: A single radar measurement of a catalog object.
      properties:
        id:
          type: integer
        catalogNumber:
          type: string
        noradCatalogNumber:
          type: integer
        instrument:
          type: string
        experiment:
          type: integer
        beam:
          type: integer
        group:
          type: integer
        targetPass:
          type: integer
        snr:
          type: number
        integrationTime:
          type: number
        transmittedAt:
          type: string
          format: date-time
        receivedAt:
          type: string
          format: date-time
        measuredAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        values:
          $ref: '#/components/schemas/MeasurementValues'
        corrected:
          $ref: '#/components/schemas/MeasurementValues'
        corrections:
          type: array
          items:
            $ref: '#/components/schemas/MeasurementCorrection'
    MeasurementValues:
      type: object
      description: Raw or corrected radar observables for a measurement.
      properties:
        range:
          type: number
        rangeError:
          type: number
        doppler:
          type: number
        dopplerError:
          type: number
        azimuth:
          type: number
        elevation:
          type: number
        rcs:
          type: number
          description: Radar cross section.
    MeasurementCorrection:
      type: object
      description: A correction applied to a raw measurement.
      properties:
        source:
          type: string
          description: Correction source, e.g. `leolabs`, `iri16`.
        type:
          type: string
          description: Correction type, e.g. `doppler_bias`, `range_bias`, `ionospheric`.
        value:
          type: number
        error:
          type: number
    State:
      type: object
      description: An orbital state vector for a catalog object.
      properties:
        id:
          type: integer
        catalogNumber:
          type: string
        noradCatalogNumber:
          type: integer
        timestamp:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        frames:
          type: object
          description: State expressed in one or more reference frames, e.g. `EME2000` and `TNW`.
          additionalProperties:
            $ref: '#/components/schemas/StateFrame'
        coefficients:
          type: object
          description: Fitted physical coefficients for the object.
          properties:
            fitted:
              type: object
              properties:
                drag:
                  type: number
                reflectivity:
                  type: number
        tle:
          $ref: '#/components/schemas/Tle'
    StateFrame:
      type: object
      description: Position, velocity and covariance in a single reference frame.
      properties:
        position:
          type: array
          items:
            type: number
        velocity:
          type: array
          items:
            type: number
        covariance:
          type: array
          items:
            type: array
            items:
              type: number
        covarianceExtended:
          type: array
          items:
            type: array
            items:
              type: number
    Tle:
      type: object
      description: A two-line element set derived from a LeoLabs state vector.
      properties:
        catalogNumber:
          type: string
    Propagation:
      type: object
      description: A propagated ephemeris derived from a state vector.
      properties:
        state:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        timestep:
          type: number
        frame:
          type: string
          description: Reference frame of the propagation, e.g. `EME2000`.
        propagation:
          type: array
          items:
            type: object
            properties:
              position:
                type: array
                items:
                  type: number
              velocity:
                type: array
                items:
                  type: number
              covariance:
                type: array
                items:
                  type: array
                  items:
                    type: number
    TaskRef:
      type: object
      description: A reference to a created tasking request.
      properties:
        id:
          type: integer
    Error:
      type: object
      description: |
        Error envelope. The official LeoLabs client falls back to `{"error": "unknown"}` when a failed
        response body cannot be parsed as JSON, indicating a top-level `error` member.
      properties:
        error:
          type: string