Skip to main content

Quick-Start Guide

Quick-Start

This page skips over some details to get a new user uploading trajectories to the staging environment in 15 minutes.

Your first API calls​

Using your client.key and client.crt, you can authenticate with the API:

The examples below show how to call that endpoint using the curl command-line utility with the --key and --cert arguments, or the Python requests library with client certs:

Get operator information​

The GET /api/v1/operator endpoint allows you to see the contact information of all the operators in the system.

$ curl --key client.key --cert client.crt -X 'GET' 'https://staging.space-safety.starlink.com/api/v1/operator' -H 'accept: text/plain'

Create an object​

The POST /api/v1/object endpoint can be used to create a new object associated with your account. You'll need the UUID that is your operator_id to create a new object. (in the examples below, 3fa85f64-5717-4562-b3fc-2c963f66afa6) You'll also have to specify the object's hard-body radius (in meters), maneuverability, its NORAD ID, and a unique name:

curl --key client.key --cert client.crt -X 'POST' \
  'https://staging.space-safety.starlink.com/api/v1/object' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "hard_body_radius": 10,
  "maneuverability": true,
  "norad_id": 0,
  "object_name": "MYSAT-1",
  "operator_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

The response will contain the UUID4 corresponding to the newly-created object. You can query objects associated with your account using the GET /api/v1/object endpoint.

Upload a trajectory​

Now that you've created an object associated with your account, you can upload a trajectory associated with that object via the POST /api/v1/trajectory endpoint. You'll need a trajectory file in OEM format, the object ID from the previous step (we'll use 4411f40a-6153-4b0b-97d4-fe9e4f59b102 below), and a trajectory type (we'll use "hypothetical" for now, see "Trajectory Submission Types" for more information).

Here's a sample OEM file in the proper format. Modify the object name to match your newly-created object, and the timestamps to be in the future:

Sample OEM File
CCSDS_OEM_VERS = 3.0
CREATION_DATE = 2023-11-06T02:08:15.481374Z
ORIGINATOR = SPACEX/USA
 
META_START
OBJECT_NAME = STARLINK-3179
OBJECT_ID = 31790
CENTER_NAME = EARTH
REF_FRAME = ITRF
TIME_SYSTEM = UTC
START_TIME = 2023-11-06T02:09:42.000000Z
STOP_TIME = 2023-11-06T02:15:42.000000Z
META_STOP
 
2023-11-06T02:09:42.000000Z -4.542752e+03 -3.316417e+03 3.877276e+03 4.819418e+00 9.779460e-02 5.717377e+00
2023-11-06T02:10:42.000000Z -4.243593e+03 -3.304426e+03 4.211322e+03 5.149116e+00 3.012760e-01 5.413318e+00
2023-11-06T02:11:42.000000Z -3.925285e+03 -3.280348e+03 4.526387e+03 5.457463e+00 5.005622e-01 5.084935e+00
2023-11-06T02:12:42.000000Z -3.589152e+03 -3.244456e+03 4.821057e+03 5.743052e+00 6.949538e-01 4.733722e+00
2023-11-06T02:13:42.000000Z -3.236600e+03 -3.197065e+03 5.094009e+03 6.004573e+00 8.837872e-01 4.361276e+00
2023-11-06T02:14:42.000000Z -2.869109e+03 -3.138526e+03 5.344019e+03 6.240812e+00 1.066436e+00 3.969275e+00
2023-11-06T02:15:42.000000Z -2.488230e+03 -3.069228e+03 5.569967e+03 6.450669e+00 1.242312e+00 3.559489e+00
 
 
COVARIANCE_START
EPOCH = 2023-11-06T02:09:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:10:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:11:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:12:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:13:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:14:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:15:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
COVARIANCE_STOP
curl \
  --cert /path/to/client.crt \
  --key /path/to/client.key -X 'POST' 'https://staging.space-safety.starlink.com/api/v1/trajectory' \
  -H 'accept: application/json' -H 'Content-Type: application/json' \
  -d "{\"file\": \"$(awk '{printf "%s\\n", $0}' /path/to/oem.txt)\", \"object_id\": \"4411f40a-6153-4b0b-97d4-fe9e4f59b102\", \"upload_type\": \"hypothetical\"}"

If you receive a 200 or 201 response, that means the system accepted your trajectory!

For more on trajectory requirements, trajectory types, and other optional parameters, see the Trajectories page

Next Steps​

The next section will give a more in-depth overview into the architecture of the screening service.

The full API specification is available via the API Reference