Import

POST/import/tle

POST/import/ephemeris

Purpose

Builds a constellation from real objects rather than a design. POST /import/tle takes NORAD two-line element text; POST /import/ephemeris takes a tabulated CCSDS OEM or SP3 trajectory.

The import path determines which propagation model is valid afterwards, and neither leaves you a choice.

POST /import/tle

Request

Parameter	Type	Unit	Default	Required	Description
`name`	string	n/a	—	Yes	Constellation name for the imported fleet.
`content`	string	n/a	—	Yes	Raw TLE text, inline. Two-line or three-line named sets, as served by CelesTrak or Space-Track.
`fov_deg`	number	deg	`45`	No	Payload field of view assigned to every imported satellite. TLEs carry no payload information.
`reference_epoch`	string	RFC 3339 UTC	—	No	Common reference epoch. Defaults to the earliest TLE epoch in the set.

content is the TLE text itself, not a path. The service does not read files from disk, which is what makes it usable from another host. Newlines are significant and must be preserved in the JSON string as \n.

Example


curl -s -X POST http://127.0.0.1:8080/import/tle \
  -H 'content-type: application/json' \
  -d '{
        "name": "iss-demo",
        "content": "ISS (ZARYA)\n1 25544U 98067A   26176.70356236  .00009385  00000+0  17567-3 0  9997\n2 25544  51.6325 257.9368 0004376 231.2480 128.8118 15.49425151573072\n"
      }'


{
  "constellation_id": "iss-demo",
  "name": "iss-demo",
  "satellite_count": 1,
  "reference_epoch": "2026-06-25T16:53:07Z",
  "skipped": []
}

Read the reference epoch back

reference_epoch is the most important field in the response. TLEs are fitted to observations around their epoch, and propagating far from it extrapolates a fit rather than integrating physics.

Pass this value as start on subsequent analysis calls. Leaving the default start of 2026-01-01T00:00:00Z against an epoch of 2026-06-25 propagates nearly six months from the fit, and nothing in the output will indicate that the result is worthless.

skipped lists entries that could not be parsed. An empty array is what you want; a non-empty one usually means a truncated download or a checksum failure rather than genuinely bad objects.

The CLI and the API disagree on the default epoch

The CLI defaults the common epoch to the latest TLE epoch in the file and prints it as guidance. This endpoint defaults to the earliest.

For a single-object import the two coincide. For a catalog spanning several days they do not, so set reference_epoch explicitly whenever the set is heterogeneous.

POST /import/ephemeris

Imports satellites whose trajectories are supplied as a table rather than as elements, from a CCSDS OEM or an SP3-c/d file.

Format	Origin	Content
CCSDS OEM	Agency and operator interchange	State vectors at tabulated epochs, with declared frame, time system, and interpolation method
SP3-c/d	GNSS precise orbit products	Position, often with clock, at a fixed interval

Which model each import permits

TLEs are fitted to SGP4; the model and the data are a matched pair. Propagating imported elements with numerical or j2 produces a confidently wrong trajectory, because the elements are mean elements in SGP4’s own theory rather than osculating elements another propagator can consume.

Ephemeris imports are valid only inside the span their table covers. Outside it there is nothing to interpolate, and there is no dynamics in the file to extrapolate with.