Skip to main content

Telemetry files

Some data has no dedicated API yet: log exports, captures, spreadsheets, vendor files. Upload it here as it is. We store each file unchanged under a source label you choose, such as ground-logs or rf-captures, and read it from there.

Use Telemetry for time-series records and the topology config for your stations and satellites. Telemetry files are for everything else.

Before you begin​

Create a live key with Upload raw data (raw-data:write) on Integrations, API and MCP. Test keys cannot upload. See Authentication.

Endpoints​

Method and pathPurpose
PUT /telemetry/files/{source}/{name}Upload one file. Needs raw-data:write.
GET /telemetry/filesList the files you have uploaded. Needs raw-data:write.
GET /telemetry/files/whoamiShow your account and your SFTP host. Needs raw-data:write.

Upload a file​

The request body is the file itself, in any format. source groups related files; name is the file's name. Both may use letters, digits, ., _ and -, up to 128 characters, and cannot be . or ...

curl -X PUT https://api.constellation.space/telemetry/files/ground-logs/2026-10-28.csv \
-H "x-api-key: $CONSTELLATION_API_KEY" \
--data-binary @2026-10-28.csv

A 201 means the file is stored:

{
"key": "...",
"size": 48213,
"sha256": "9f2c...",
"received_at": "2026-10-28T14:02:11.123456Z"
}
FieldDescription
keyWhere the file is stored. Quote it when you ask us about a file.
sizeBytes received.
sha256SHA-256 of the bytes received. Compare it with your own to confirm the upload is intact.
received_atWhen the file was stored.

Each upload is stored as a new file, so uploading the same name again never replaces an earlier one.

List your files​

GET /telemetry/files returns your own files only. Every parameter is optional.

ParameterDescription
sourceOnly files under this source.
sinceOnly files received since this time, with a UTC offset.
limitThe most files to return in one page, from 1 to 1,000. Default 100.
cursorThe next value from the previous page.
curl -G https://api.constellation.space/telemetry/files \
-H "x-api-key: $CONSTELLATION_API_KEY" \
-d source=ground-logs
{
"items": [
{ "key": "...", "source": "ground-logs", "name": "2026-10-28.csv", "size": 48213, "received_at": "2026-10-28T14:02:11.123456Z" }
],
"next": null
}

When next is not null, pass it as cursor to read the next page. since filters each page, so a page can be short or empty while next is still set.

Large files over SFTP​

An HTTPS upload takes up to 10 MB (10,000,000 bytes). For larger files, use SFTP. It is available on api.constellation.space; a private deployment may not offer it. GET /telemetry/files/whoami returns your SFTP host; sftp_host is null where SFTP is not available.

curl https://api.constellation.space/telemetry/files/whoami -H "x-api-key: $CONSTELLATION_API_KEY"

Connect as user api. The password is your API key. You start in your account's folder. Put each file in a folder named after its source:

sftp api@<sftp_host>
# Password: your API key
sftp> mkdir rf-captures
sftp> put capture-0412.bin rf-captures/

Files you upload over SFTP appear in GET /telemetry/files like HTTPS uploads, under the folder's name as their source. Unlike HTTPS, putting a file with the same name in the same folder replaces it.

Over SFTP you can upload, download and list your files, but not delete or rename them. Some clients upload to a temporary name and rename it when the transfer finishes, which fails with Permission denied. Turn that off: in WinSCP, under Preferences > Transfer > Endurance, set Enable transfer resume/transfer to temporary filename for to Disable. The command-line sftp client writes the final name directly.

Isolation​

Each account sees and writes only its own files. A key cannot list or read another account's uploads. On an enterprise deployment, each tenant account is isolated the same way. See Tenant isolation.

Errors​

StatusErrorFix
400invalid_name, with fieldsource or name breaks the naming rule above. Rename it.
400invalid_cursorThe cursor is not a next value. Start the listing again.
401auth_failedThe key is missing, wrong, expired, or revoked.
403insufficient_scope, with requiredThe key lacks raw-data:write. Create a key with Upload raw data.
403sandbox_read_onlyA test key tried to upload. Use a live key.
403account_disabledThe account is disabled. Contact support.
413too_large, with max_bytesThe file is over the HTTPS limit. Use SFTP if it is enabled for you.
503raw_data_unavailableRaw data storage is unavailable. Retry later.
503entitlement_unavailableThe account could not be checked. Retry later.

See Errors and limits for rate limits and lockouts.