Skip to main content

API Endpoints

GET /satellites​

Returns all taskable satellites and their supported window types and payloads. See the example JSON response to the right.

curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/satellites"
{
  "data": [
    {
      "id": "FM123",
      "norad_id": "12345",
      "supported_windows": [
          "PAYLOAD_SDR",
          "PAYLOAD_SABERTOOTH"
      ],
      "supported_payloads": [
          "SDR",
          "SABERTOOTH"
      ]
    }
  ]
}

GET /availability​

Return time ranges between start and end during which the user may schedule a window of the specified type. See the example JSON response to the right.

Arguments​

NameTypeRequiredDescription
satellite_idstringyes
window_typestringyesSee Supported Windows
startintegeryesepoch time
durationintegeryesseconds
paired_satellite_idstringnoFor window types that involve a pair of satellites (such as LEASE_ISL) this is the other satellite's satellite_id

Response​

NameTypeDescription
availablelistlist of periods window can be scheduled within
SATELLITE_ID="satellite_id=FM123"
WINDOW_TYPE="window_type=PAYLOAD_SDR"
START="start=$(date -u +%s)"
DURATION="duration=86400"  # One day
QUERY_PARAMS="${SATELLITE_ID}&${WINDOW_TYPE}&${START}&${DURATION}"

curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/availability?${QUERY_PARAMS}"
{
  "data": {
    "available": [
      { "start": 1599445000, "end": 1599473800 },
      { "start": 1599474400, "end": 1599503200 },
      { "start": 1599503800, "end": 1599531400 }
    ]
  }
}

POST /upload​

Submit a file for upload to target satellite. The response is a JSON payload containing the ID of the upload request. See the example JSON response to the right.

No assumptions should be made regarding the structure of the ID.

Arguments​

NameTypeRequiredDescription
satellite_idstringyes
payloadstringyesSee Supported Payloads
destination_pathstringyespath on payload
executablebooleanyes
filemultipart-encoded fileyes
itarbooleannoITAR-tagged uploads will only be uploaded through US-based ground stations (default: false)
SATELLITE_ID="satellite_id=FM123"
PAYLOAD="payload=SABERTOOTH"
DESTINATION_PATH="destination_path=/persist/bin/phase1"
EXECUTABLE="executable=true"
QUERY_PARAMS="${SATELLITE_ID}&${PAYLOAD}&${DESTINATION_PATH}&${EXECUTABLE}"

# Create test file to upload
echo "test" > phase1

curl -X POST "${HOST}/tasking/upload?${QUERY_PARAMS}" \
-H "${AUTH_HEADER}"  \
-F "file=@phase1"
{"data": {"id": "8f76a939-609e-4042-8c97-079031af0320"}}

GET /uploads​

Returns information on files previously submitted for uploading. See the example JSON response to the right.

Additional Response Fields​

NameTypeDescription
idstringidentifer for upload
statusstring"PENDING", "UPLOADING", or "UPLOADED"
last_updatefloattimestamp of the last time the record has been updated (file has started/finished uploading, or a new segment has been uploaded)
progressfloatCurrent file progress (in percent)
curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/uploads"
{
  "data": [
    {
      "satellite_id": "FM123",
      "payload": "SDR",
      "destination_path": "/persist/bin/phase1",
      "executable": true,
      "status": "PENDING",
      "id": "71c92e3c57bc440ea89d76c94cdf387f",
      "progress": 0,
      "last_update": 1659700499.978814
    },
    {
      "satellite_id": "FM123",
      "payload": "SABERTOOTH",
      "destination_path": "/persist/bin/phase2",
      "executable": true,
      "status": "UPLOADING",
      "id": "796392e80df14f46b07b86e13d3240ec",
      "progress": 13.33456773,
      "last_update": 1659702459.978814
    },
    {
      "satellite_id": "FM123",
      "payload": "SDR",
      "destination_path": "/persist/config/fir.txt",
      "executable": false,
      "status": "UPLOADED",
      "id": "45c59b08df97477a84af75ca2882859a",
      "progress": 100,
      "last_update": 1659730499.938517
    }
  ]
}

POST /window​

Schedule a new operation window. Each window type supports specific tuning arguments via the parameters field. The set of available payload window types and their supported parameters can be found at Supported Windows.

The server will respond to the request with the ID of the scheduled window in a JSON payload. See the example JSON response to the right.

No assumptions should be made regarding the structure of the ID.

Note that if a window is meant to have a paired window scheduled on a paired satellite (e.g. LEASE_ISL), it will be automatically scheduled, as well.

Arguments​

NameTypeRequiredDescription
typestringyesSee Supported Windows
satellite_idstringyes
startintegeryesepoch time
durationintegeryesseconds
parametersparametersyesSee window parameters

Response​

NameTypeDescription
idstringidentifier for window
curl -X POST "${HOST}/tasking/window" \
-H "${AUTH_HEADER}" \
-H "Content-Type: application/json" \
-d @- << EOF
{
    "type": "PAYLOAD_SABERTOOTH",
    "satellite_id": "FM123",
    "start": 1599503800,
    "duration": 600,
    "parameters": {
        "downlink_budget": 0,
        "user_command": {
            "executable": "/persist/bin/generate_waveform",
            "executable_arguments": [
                "--period", "100",
                "--amplitude", "200"
            ]
        }
    }
}
EOF
{"data": {"id": "3014288"}}

GET /contacts​

List the latest contacts for a given satellite. The json object returned has two elements:

  • "data": a list of contact windows
  • "next": if there are additional contacts available beyond the requested time bounds, a link to the next page will be provided. If no more data is available, this field will have a value of null See the example JSON response.

Valid statuses​

StatusDescription
PENDING_SYNCThe contact has been accepted by the API but not yet transferred to the satellite
SYNCEDThe contact has been transferred to the satellite

Valid Types​

StatusDescription
BIDIRThe contact involves two-way transmissions between the satellite and a receiver
TXOThe contact involves only one-way satellite to receiver transmissions
RXOThe contact involves only one-way receiver to satellite transmissions

Arguments​

NameTypeRequiredDescription
satellite_idstringyes
start_ltfloat (epoch timestamp)noAn "upper" bound, returns all contacts with start time less than the provided epoch. May be used with or without the start_gt argument
start_gtfloat (epoch timestamp)noA "lower" bound, returns all contacts with start time greater than the provided epoch. May be used with or without the start_lt argument

Response​

NameTypeDescription
idstringidentifier for contact
SATELLITE_ID="satellite_id=FM123"
START_LT="start_lt=1648684800" # 2022-03-31 00:00 UTC
QUERY_PARAMS="${SATELLITE_ID}&${START_LT}"


curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/contacts?${QUERY_PARAMS}"

If more values are available, next will contain the URL to the next page

{
  "data": [{
        "id": "5f7770a7984c4b30856a3a810c1b3e2f",
        "type": "BIDIR",
        "satellite_id": "FM123",
        "state": "PENDING_SYNC",
        "start": 1599503800,
        "duration": 600,
      },
      //...
  ],
  "next": "https://api.orb.spire.com/tasking/contacts?satellite_id=FM123&start_lt=1599553800"
}

If there are no more values available, next will be null

{
  "data": [{
        "id": "5f7770a7984c4b30856a3a810c1b3e2f",
        "type": "BIDIR",
        "satellite_id": "FM123",
        //...
      }
  ],
  "next": null
}

GET /windows​

List the latest windows for a given satellite. The json object returned has two elements:

  • "data": a list of payload windows
  • "next": if there are additional windows available beyond the requested time bounds, a link to the next page will be provided. If no more data is available, this field will have a value of null

See the example JSON response.

Valid Synchronization States​

StatusDescription
PENDING_SYNCThe window has been accepted by the API but not yet transferred to the satellite
SYNCEDThe window has been transferred to the satellite
FAILED_SYNCThe window has not been transferred to the satellite in time for execution and will not execute
PENDING_DELETIONA request to delete the window has been accepted by the API but not yet confirmed
UNKNOWNThe window is in an unknown state, contact a Spire representative to resolve

Once a window is in the PENDING_DELETION state, its interval is no longer considered unavailable, so it will be possible to schedule a new window overlapping this interval, provided other conditions for the new window are met.

Once deletion of the window is confirmed, it is no longer listed in the GET /windows response.

Arguments​

NameTypeRequiredDescription
satellite_idstringyes
plw_start_ltfloat (epoch timestamp)noAn "upper" bound, returns all windows with start time less than the provided epoch. May be used with or without the plw_start_gt argument
plw_start_gtfloat (epoch timestamp)noA "lower" bound, returns all windows with start time greater than the provided epoch. May be used with or without the plw_start_lt argument

Response​

NameTypeDescriptionLog Time
idstringidentifier for windowGenerated when window POST command is called to create a new window
exit_statusstringA success indicator for the given window, reading either "FAILED"/"SUCCESSFUL", and null if not yet loggedUpdated when associated logged telemetry is downloaded upon window completion
ran_durationfloatthe delta between the observed payload power on and the initiated window end. "null" if not yet logged
SATELLITE_ID="satellite_id=FM123"
PLW_START_LT="plw_start_lt=1648684800" # 2022-03-31 00:00 UTC
QUERY_PARAMS="${SATELLITE_ID}&${PLW_START_LT}"


curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/windows?${QUERY_PARAMS}"

If more values are available, next will contain the URL to the next page

{
  "data": [{
        "id": "5260382",
        "type": "PAYLOAD_SABERTOOTH",
        "satellite_id": "FM123",
        "state": "PENDING_SYNC",
        "start": 1599503800,
        "duration": 600,
        "parameters": {
          "user_command": {
            "executable": "/persist/bin/generate_waveform.sh",
            "executable_arguments": [
              "--period", "100",
              "--amplitude", "200"
            ],
          }
        },
        "exit_status": null,
        "ran_duration": null,
      },
      //...
  ],
  "next": "https://api.orb.spire.com/tasking/windows?satellite_id=FM123&plw_start_lt=1599553800"
}

If there are no more values available, next will be null

{
  "data": [{
        "id": "5f7770a7984c4b30856a3a810c1b3e2f",
        "type": "PAYLOAD_SABERTOOTH",
        "satellite_id": "FM123",
        //...
      }
  ],
  "next": null
}

GET /window​

List the synchronization information for a given satellite window, keyed off the requested window "id". The json object returned has the same structure as a given window element in the GET /windows return.

In addition to displaying all synchronization information available via GET /windows, the GET /window endpoint will offer additional information and statistics about the files generated during a window, post-capture.

Response​

NameTypeDescriptionLog Time
file_outputdictionaryA dictionary whose keys are all files generated by an associated capture, along with select file and download metrics mapped to those keys (detailed below)Logged as telemetry when a file is received on the OBC for download from a given payload agent. This telemetry, too, will need to download prior to display

file_output Schema​

The "file_output" entry will return a dictionary, the keys of which are the names of files generated by a customers requested payload capture. Stored under each filename key entry will be another dictionary with file statistics.

NameTypeDescriptionEmpty Value
sizeintthe size of the generated file in question, measured in kB0
update_timeDate & TimestampA human readable timestamp indicating the log time of the most recent file output telemetry message.None
download_progressfloatAn indication of an associated file's download progress, ranging from 0.0 to 1.0, where intermediate progress reports are rounded to the hundredths decimal place (e.g. 0.01)0.0

See the example JSON response.

ID=5260382
QUERY_PARAMS="${WINDOW_ID}"


curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/window?${QUERY_PARAMS}"
{
  "data": {
    "id": "5260382",
    "type": "PAYLOAD_SABERTOOTH",
    "satellite_id": "FM123",
    "state": "SYNCED",
    "start": 1599503800,
    "duration": 600,
    "parameters": {
      "user_command": {
        "executable": "/persist/bin/generate_waveform.sh",
        "executable_arguments": [
          "--period", "100",
          "--amplitude", "200"
        ]
      }
    },
    "exit_status": "SUCCESSFUL",
    "ran_duration": 590.026757,
    "file_output": {
        "path1": {"size": 1180, "update_time": "2024-07-31 22:46:13", "download_progress": 0.0},
        "path2": {"size": 7920, "update_time": "2024-07-31 22:46:13", "download_progress": 0.82},
        "path3": {"size": 8532, "update_time": "2024-07-31 22:46:13", "download_progress": 1.0}
    }
  }
}

Minimum Version Requirements for 'download_progress'​

Displaying download_progress statistics for a given window and file pairing requires that a minimum set of versioned software packages are present for a customer's payload setup.

  1. The Spire Linux Agent active on the payload must be v1.5.1 or newer
  2. When sending files to the Spire Linux Agent via the SDK SendFileRequest package, the 'payload_exec' executable on this payload must pass the window 'id' (as a string) to SendOptions (schema found here) -> 'tags' -> 'token'. The window id is available as an argument to each payload_exec call. For additional details and examples, please review the Spire Linux Agent documentation.
    • Note: this must be true on a per-payload basis
  3. The window id in question must have executed on a payload where the version requirement 1 and 2 are met, (it cannot be applied retroactively)

DELETE /window​

Request for a window to be deleted. If the window is in a PENDING_SYNC or SYNCED state this will move it to the PENDING_DELETION state. The deletion request may be rejected if there is no opportunity to confirm deletion with the satellite. Once deletion is confirmed the window will no longer appear in the GET /windows response. If deletion cannot be confirmed the window may still execute. If the window has a paired window that was automatically scheduled on a paired satellite, the deletion of the paired window will be attempted during this request, too. Only both windows will be deleted if they both meet the deletion requirement outlined above.

If the request is successful, the endpoint will return the id of the deleted window.

Arguments​

NameTypeRequiredDescription
idstringyesidentifier for window to delete
ID="id=3014288"
QUERY_PARAMS="${ID}"

curl -X DELETE -H "${AUTH_HEADER}" "${HOST}/tasking/window?${QUERY_PARAMS}"
{"data": {"id": "3014288"}}

DELETE /upload​

Remove a previously-requested upload from the upload queue.

If the specified file has already been uploaded to the satellite, an error will be throw.

If the upload is in progress, no further attempts to complete the file will be made.

If the request is successful, the endpoint will return the id of the deleted window.

Arguments​

NameTypeRequiredDescription
idstringyesidentifier for upload to delete
ID="id=796392e80df14f46b07b86e13d3240ec"
QUERY_PARAMS="${ID}"

curl -X DELETE -H "${AUTH_HEADER}" "${HOST}/tasking/upload?${QUERY_PARAMS}"
{"data": {"id": "796392e80df14f46b07b86e13d3240ec"}}

GET /quota​

List the quota usage within an interval. Usage for each individual quota is returned for each quota "period" that overlaps with the request interval. Where a per-satellite quota exists, individual usage is detailed for each satellite. GLOBAL quotas are cummulative across satellites.

See the example JSON response.

Arguments​

NameTypeRequiredDescription
startintegeryesepoch time
durationintegeryesseconds

Response​

NameTypeDescription
scopestring"PER_SATELLITE", "GLOBAL"
resourcestring"TASKING_DURATION", "DATA_GENERATION_VOLUME"
usagefloatquota usage in the associated quota period
quotafloatquota allowance in the associated quota period
unitstringunit of measurement of the usage and quota
quota_startstringepoch time of the start of the quota period
quota_endstringepoch time of the end of the quota period
basisstringquota period basis - only "PER_DAY" is currently supported
window_typestringif the quota is specific to a window type
satellite_idstringif scope is "PER_SATELLITE"
START="start=1707782400" # 2024-02-13 00:00 UTC
DURATION="duration=10"
QUERY_PARAMS="${START}&${DURATION}"


curl -X GET -H "${AUTH_HEADER}" "${HOST}/tasking/quota?${QUERY_PARAMS}"
{
  "data": {
    "quotas": [
      {
        "scope": "PER_SATELLITE",
        "resource": "TASKING_DURATION",
        "usage": 0.5,
        "quota": 1,
        "unit": "hour",
        "quota_start": 1707782400,
        "quota_end": 1707868799,
        "basis": "PER_DAY",
        "window_type": "PAYLOAD_SDR",
        "satellite_id": "FM123"
      },
      {
        "scope": "GLOBAL",
        "resource": "TASKING_DURATION",
        "usage": 0.5,
        "quota": 1,
        "unit": "hour",
        "quota_start": 1707782400,
        "quota_end": 1707868799,
        "basis": "PER_DAY",
        "window_type": "PAYLOAD_SDR"
      },
      {
        "scope": "PER_SATELLITE",
        "resource": "DATA_GENERATION_VOLUME",
        "usage": 0.2,
        "quota": 1,
        "unit": "GB",
        "quota_start": 1707782400,
        "quota_end": 1707868799,
        "basis": "PER_DAY",
        "window_type": "PAYLOAD_SDR",
        "satellite_id": "FM123"
      },
    ]
  }
}