Data Access API

The SDC provides a REST API that allows users to upload and download files, as well as query for file metadata. The following documentation describes the various endpoints that are supported and how to use them.

The API can be accessed from the following URL: https://api.dev.imap-mission.com

Upload

GET /upload/science/{filepath}

Upload a science file to the SDC

Parameters:

• filepath (string) – 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}/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf). The filename must be a valid IMAP filename that follows the conventions described here.

Status Codes:

• 200 OK – Successful upload

• 400 Bad Request – Invalid or missing filename

Example Usage:

curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/upload/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf

Possible Responses:

{"statusCode": 200, "body": "https://sds-data.s3.amazon.com/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf?<credentials-string>"}
{"statusCode": 400, "body": "A pre-signed URL could not be generated. Please ensure that the file name matches mission file naming conventions."}

Download

GET /download/{filepath-or-filename}

Download a file from the SDC

Parameters:

• filepath-or-filename (string) –

  The filename to download (e.g. imap_codice_l1a_lo_20260101_20260102_v01-01.cdf, optionally including the full filepath (e.g. codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf). The filename must be a valid IMAP filename that follows the conventions described here.

Status Codes:

• 302 Found – Successful download

• 400 Bad Request – Unsuccessful download

Example Usage:

curl -X GET -H "Accept: application/json" /codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf
curl -X GET -H "Accept: application/json" imap_codice_l1a_lo_20260101_20260102_v01-01.cdf

Possible Responses:

{"statusCode": 302, "headers": {"Content-Type": "text/html", "Location": "s3://sds-data/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01"}, "body": {"download_url": "s3://sds-data/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01"}}
{"statusCode": 400, "body": "Not a valid S3 URI.  Example input: s3://bucket/path/file.ext"}

Query

GET /query

Query for file metadata

Query Parameters:

• instrument (string) –

  The instrument of interest (e.g. mag). Supported instruments are listed here.

• data_level (string) –

  The level of data product (e.g. l1a). Supported levels are listed here.

• descriptor (string) –

  The descriptor of interest (e.g. burst). Supported descriptors are listed here.

• start_date (string) – Search for all files with a start date on or after this time, in the format YYYYMMDD.

• end_date (string) – Search for all files with a start date on or before this time, in the format YYYYMMDD.

• version (string) – The version of data product in the format vXX-YY (e.g. v01-01).

• extension (string) – The file extension of interest (e.g. cdf). Supported extensions include pkts and cdf.

Status Codes:

• 200 OK – Successful query

• 400 Bad Request – Unsuccessful query

Example Usage:

curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/query?instrument=mag&data_level=l0&descriptor=burst&start_date=20230112&end_date=20230113&version=*&extension=pkts

Possible Responses:

{"statusCode": 200, "headers": {"Content-Type": "application/json", "Access-Control-Allow-Origin": "*"}, "body": "[('mag', 'l0', 'burst', '20230112', '20230113', 'v01-01', 'pkts'), ('mag', 'l0', 'burst', '20230112', '20230113', 'v01-02', 'pkts')]"}
{"statusCode": 400, "headers": {"Content-Type": "application/json", "Access-Control-Allow-Origin": "*"}, "body": "<param> is not a valid query parameter. Valid query parameters are: <valid parameters>"}