openapi.yml

openapi: 3.0.0
servers:
  - description: Production IMAP SDC Server
host: https://api.imap-mission.com/
info:
  version: "0.1.0"
  title: IMAP SDC API
  description: Describes the API endpoints for interacting with the IMAP SDC

paths:

  '/upload/{filepath}':
    get:
      tags:
        - Upload
      summary: Upload a science file to the SDC
      parameters:
        - name: filepath
          in: path
          required: true
          description: |
            The full path to the file to upload, relative to the ``IMAP_DATA_DIR`` environment variable or the user's
            current working directory. (e.g. ``{IMAP_DATA_DIR}/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts``).
            The filename must be a valid IMAP Science or ancillary filename that follows the conventions described in our :ref:`naming conventions <naming-conventions>`.
          schema:
            type: string
        - name: X-api-key
          in: header
          required: false
          description: |
            The API key for authentication. This key is used to authorize the upload request. (Optional for now).
          schema:
            type: string

      responses:
        '200':
          description: Pre-signed URL for upload
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
        '400':
          description: Invalid or missing filename
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '409':
          description: File already exists
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    put:
      tags:
        - Upload
      summary: Upload a science file to the SDC via pre-signed URL
      parameters:
        - name: URL
          in: path
          required: true
          description: |
            The pre-signed URL for uploading the file. This URL is generated by the GET request to the
            ``/upload/{filepath}`` endpoint.
          schema:
            type: string
        - name: data
          in: path
          required: true
          description: |
              The file data to be uploaded. This should be the binary content of the file.
          schema:
            type: string

      responses:
        '200':
          description: Successful upload
          content:
              application/json:
                  schema:
                    type: array
                    items:
                      type: string


  '/download/{filepath}':
    get:
      tags:
        - Download
      summary: Download a file from the SDC
      operationId: download
      parameters:
        - in: path
          name: filepath
          description: |
            The full path to the file to download (e.g.
            ``imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts``). The filename must be a valid science or ancillary IMAP
            filename that follows the conventions described in our :ref:`naming conventions <naming-conventions>`.
          required: true
          schema:
            type: string
      responses:
        '302':
          description: Successful download
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
        '400':
          description: Missing filename
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
        '404':
          description: File not found
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri

  '/query':
    get:
      tags:
        - Query
      summary: Query for file metadata
      operationId: query
      parameters:
        - in: query
          name: table
          description: |
            The database table of interest (e.g. ``science`` or ``ancillary``) for the query to perform against.
            The default option is the ``science`` table.
          required: false
          schema:
            type: string
        - in: query
          name: instrument
          description: |
            The instrument of interest (e.g. ``mag``). Supported instruments are listed
            in our :ref:`naming conventions <naming-conventions>`.
          required: false
          schema:
            type: string
        - in: query
          name: data_level
          description: |
            The level of data product (e.g. ``l1a``). Supported levels are listed
            in our :ref:`naming conventions <naming-conventions>`.
          required: false
          schema:
            type: string
        - in: query
          name: descriptor
          description: |
            The descriptor of interest (e.g. ``burst``). Supported descriptors are listed
            in our :ref:`naming conventions <naming-conventions>`.
          required: false
          schema:
            type: string
        - in: query
          name: start_date
          description: Search for all files with a start date on or after this time, in the format ``YYYYMMDD``.
          required: false
          schema:
            type: string
        - in: query
          name: end_date
          description: Search for all files with a start date on or before this time, in the format ``YYYYMMDD``.
          required: false
          schema:
            type: string
        - in: query
          name: ingestion_start_date
          description: Search for all files with an ingestion start date on or after this time, in the format ``YYYYMMDD``.
          required: false
          schema:
            type: string
        - in: query
          name: ingestion_end_date
          description: Search for all files with an ingestion start date on or before this time, in the format ``YYYYMMDD``.
          required: false
          schema:
            type: string
        - in: query
          name: version
          description: The version of data product in the format ``vNNN`` (e.g. ``v001``). You can also choose to
            query ``--version latest`` in order to receive the most recent version of a file.
          required: false
          schema:
            type: string
        - in: query
          name: extension
          description: The file extension of interest (e.g. ``cdf``). Supported extensions include ``pkts`` and ``cdf``.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
        '400':
          description: Unsuccessful query
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri

  '/spice-query':
    get:
      tags:
        - SPICE Query
      summary: Query for SPICE kernel metadata
      operationId: spice-query
      parameters:
        - in: query
          name: file_name
          description: |
            The name of a specific SPICE kernel file (e.g. ``naif0012.tls``).
          required: false
          schema:
            type: string
        - in: query
          name: start_time
          description: |
            Coverage start time in TDB seconds since J2000. Returns kernels whose
            coverage ends on or after this time.
          required: false
          schema:
            type: string
        - in: query
          name: end_time
          description: |
            Coverage end time in TDB seconds since J2000. Returns kernels whose
            coverage begins on or before this time.
          required: false
          schema:
            type: string
        - in: query
          name: type
          description: |
            The SPICE kernel type to filter by. Accepted values are:
            ``leapseconds``, ``planetary_constants``, ``imap_frames``,
            ``science_frames``, ``spacecraft_clock``, ``earth_attitude``,
            ``planetary_ephemeris``, ``ephemeris_reconstructed``,
            ``ephemeris_nominal``, ``ephemeris_predicted``, ``ephemeris_90days``,
            ``ephemeris_long``, ``ephemeris_launch``, ``attitude_history``,
            ``attitude_predict``, ``pointing_attitude``.
          required: false
          schema:
            type: string
        - in: query
          name: latest
          description: |
            If ``True``, only return the latest version of each kernel matching
            the other query parameters.
          required: false
          schema:
            type: string
        - in: query
          name: start_ingest_date
          description: |
            Filter results to kernels ingested on or after this date, in the
            format ``YYYYMMDD``.
          required: false
          schema:
            type: string
        - in: query
          name: end_ingest_date
          description: |
            Filter results to kernels ingested on or before this date, in the
            format ``YYYYMMDD``.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful query — returns a list of SPICE kernel metadata objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: Invalid query parameter or parameter value
          content:
            application/json:
              schema:
                type: string

  '/metakernel':
    get:
      tags:
        - SPICE Query
      summary: Retrieve a metakernel or list of SPICE kernel filenames for a time range
      operationId: metakernel
      parameters:
        - in: query
          name: start_time
          description: |
            Coverage start time. Accepts either TDB seconds since J2000 or a date
            string in the format ``YYYYMMDD``.
          required: true
          schema:
            type: string
        - in: query
          name: end_time
          description: |
            Coverage end time. Accepts either TDB seconds since J2000 or a date
            string in the format ``YYYYMMDD``.
          required: true
          schema:
            type: string
        - in: query
          name: spice_path
          description: |
            Root path for the SPICE directory. This path is prepended to all kernel file
            locations in the returned metakernel. If omitted the paths are left
            relative. Only applicable if ``list_files``` is ``False``.
          required: false
          schema:
            type: string
        - in: query
          name: list_files
          description: |
            If ``True``, return only a list of kernel filenames instead of a full
            metakernel file.
          required: false
          schema:
            type: string
        - in: query
          name: require_coverage
          description: |
            If ``True``, the request will fail with a HTTP ``422`` status if there
            are any gaps in coverage for the requested time range.
          required: false
          schema:
            type: string
        - in: query
          name: file_types
          description: |
            Comma-separated list of kernel types to include. If omitted, all
            available kernel types are included. Accepted values are:
            ``leapseconds``, ``planetary_constants``, ``imap_frames``,
            ``science_frames``, ``spacecraft_clock``, ``earth_attitude``,
            ``planetary_ephemeris``, ``ephemeris_reconstructed``,
            ``ephemeris_nominal``, ``ephemeris_predicted``, ``ephemeris_90days``,
            ``ephemeris_long``, ``ephemeris_launch``, ``attitude_history``,
            ``attitude_predict``, ``pointing_attitude``.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful response. Returns a metakernel file (text/plain) when
            ``list_files`` is ``False`` (default), or a JSON array of kernel
            filenames when ``list_files`` is ``True``.
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  type: string
        '404':
          description: No kernel files found for the requested time range
          content:
            application/json:
              schema:
                type: string
        '422':
          description: |
            Coverage gaps detected when ``require_coverage=True``. The response
            body contains a list of the gap intervals.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object