Files · Stellar Control

GET/v1/targets/{target}/files

List files#

On-board directory

The files of the last listings of the target (the instances of its files component in the current value table), by identifier, with the date each was last listed and the state of its transfer.

Path parameters

targetrequired

string

Target, as named in the topology (sim-1).

Responses

200The directory.application/json

componentrequired

string

Component of the on-board directory.

filesrequired

array of OnboardFile

Files, by identifier.

OnboardFile · 7 fields

idrequired

string

Identifier.

file_type

string

Type (lttm, log…).

size

integer · int64

Size, in bytes.

≥ 0

checksum

string

Checksum, hexadecimal.

generation

integer · int64

Generation: a file rewritten on board gets the next one.

≥ 0

transfer

string

State of its transfer.

listed_at

string · date-time

Last listing.

404Unknown target, or no on-board directory: files::no-directory.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/targets/<target>/files"

import requests

BASE_URL = "http://localhost:8080"
target = "<target>"  # Target, as named in the topology (`sim-1`).

response = requests.get(f"{BASE_URL}/v1/targets/{target}/files")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";
let target = "<target>"; // Target, as named in the topology (`sim-1`).

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/targets/{target}/files"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "component": "string",
  "files": [
    {
      "id": "string",
      "file_type": "string",
      "size": 0,
      "checksum": "string",
      "generation": 0,
      "transfer": "string",
      "listed_at": "2026-09-29T08:30:00Z"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/targets/{target}/files/refresh

Refresh files#

List the on-board directory

Sends the listing telecommand of the catalogue (transfer.list) as a direct telecommand.

Path parameters

targetrequired

string

Target, as named in the topology (sim-1).

Responses

202The listing telecommand, submitted.application/json

idrequired

string

Identifier of the telecommand.

duplicaterequired

boolean

Whether the same identifier was already submitted: nothing new is sent.

404Unknown target, or no on-board directory.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409The target is held by a run.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

422No listing telecommand: files::no-listing.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/targets/<target>/files/refresh"

import requests

BASE_URL = "http://localhost:8080"
target = "<target>"  # Target, as named in the topology (`sim-1`).

response = requests.post(f"{BASE_URL}/v1/targets/{target}/files/refresh")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";
let target = "<target>"; // Target, as named in the topology (`sim-1`).

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/targets/{target}/files/refresh"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "id": "string",
  "duplicate": true
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/transfers

List transfers#

File transfers

Query parameters

target

string

Only the transfers of this target.

Responses

200Transfers, by priority then age.application/json

transfersrequired

array of Transfer

Transfers, by priority then age.

Transfer · 15 fields

by

string

Who asked for it.

checksum

string

Checksum of the whole file, hexadecimal, as listed.

created_atrequired

string

Creation.

direction

TransferDirection

Direction.

file_idrequired

string

File identifier.

file_type

string

Type of the file (lttm…).

generationrequired

integer · uint64

Generation of the file.

≥ 0

priority

integer · int32

Priority: higher first.

default 0

reason

string

Why corrupted or superseded.

received

array of array of integer · uint64

Ranges received, [start, end) in bytes, sorted and disjoint.

sizerequired

integer · uint64

Size, in bytes.

≥ 0

source

string

Content uploaded: its hexadecimal SHA-256 in [UPLOADS_STORE].

state

TransferState

State.

targetrequired

string

Target.

updated_atrequired

string

Last change.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/transfers"

import requests

BASE_URL = "http://localhost:8080"

response = requests.get(f"{BASE_URL}/v1/transfers")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/transfers"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "transfers": [
    {
      "by": "string",
      "checksum": "string",
      "created_at": "string",
      "direction": "download",
      "file_id": "string",
      "file_type": "string",
      "generation": 0,
      "priority": 0,
      "reason": "string",
      "received": [
        [
          0
        ]
      ],
      "size": 0,
      "source": "string",
      "state": "REQUESTED",
      "target": "string",
      "updated_at": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/transfers

Create transfer#

Download an on-board file

Creates the download of the current generation of a file, as last listed; the transfer already there when it exists. The transfer manager then asks the missing ranges, pass after pass.

Request body application/jsonrequired

targetrequired

string

Target.

file_idrequired

string

File, by its on-board identifier.

priority

integer · int32

Priority: higher first.

Responses

201The transfer.application/json

by

string

Who asked for it.

checksum

string

Checksum of the whole file, hexadecimal, as listed.

created_atrequired

string

Creation.

direction

TransferDirection

Direction.

file_idrequired

string

File identifier.

file_type

string

Type of the file (lttm…).

generationrequired

integer · uint64

Generation of the file.

≥ 0

priority

integer · int32

Priority: higher first.

default 0

reason

string

Why corrupted or superseded.

received

array of array of integer · uint64

Ranges received, [start, end) in bytes, sorted and disjoint.

sizerequired

integer · uint64

Size, in bytes.

≥ 0

source

string

Content uploaded: its hexadecimal SHA-256 in [UPLOADS_STORE].

state

TransferState

State.

targetrequired

string

Target.

updated_atrequired

string

Last change.

404Unknown target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

422Invalid request, no on-board directory, or file never listed: transfer::invalid, files::no-directory, transfer::not-listed.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/transfers" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "string",
  "file_id": "string",
  "priority": 0
}'

import requests

BASE_URL = "http://localhost:8080"

response = requests.post(
    f"{BASE_URL}/v1/transfers",
    json={
        "target": "string",
        "file_id": "string",
        "priority": 0,
    },
)
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/transfers"))
    .json(&serde_json::json!({
      "target": "string",
      "file_id": "string",
      "priority": 0
    }))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "by": "string",
  "checksum": "string",
  "created_at": "string",
  "direction": "download",
  "file_id": "string",
  "file_type": "string",
  "generation": 0,
  "priority": 0,
  "reason": "string",
  "received": [
    [
      0
    ]
  ],
  "size": 0,
  "source": "string",
  "state": "REQUESTED",
  "target": "string",
  "updated_at": "string"
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/transfers/{target}/{file_id}/{generation}

Get transfer#

A file transfer

Path parameters

targetrequired

string

Target, as named in the topology (sim-1).

file_idrequired

string

On-board file identifier.

generationrequired

integer · int64

Generation of the file.

≥ 0

Query parameters

direction

string

upload for an upload; a download without.

Responses

200The transfer.application/json

by

string

Who asked for it.

checksum

string

Checksum of the whole file, hexadecimal, as listed.

created_atrequired

string

Creation.

direction

TransferDirection

Direction.

file_idrequired

string

File identifier.

file_type

string

Type of the file (lttm…).

generationrequired

integer · uint64

Generation of the file.

≥ 0

priority

integer · int32

Priority: higher first.

default 0

reason

string

Why corrupted or superseded.

received

array of array of integer · uint64

Ranges received, [start, end) in bytes, sorted and disjoint.

sizerequired

integer · uint64

Size, in bytes.

≥ 0

source

string

Content uploaded: its hexadecimal SHA-256 in [UPLOADS_STORE].

state

TransferState

State.

targetrequired

string

Target.

updated_atrequired

string

Last change.

404No such transfer: transfer::unknown.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/transfers/<target>/<file_id>/1"

import requests

BASE_URL = "http://localhost:8080"
target = "<target>"  # Target, as named in the topology (`sim-1`).
file_id = "<file_id>"  # On-board file identifier.
generation = "1"  # Generation of the file.

response = requests.get(f"{BASE_URL}/v1/transfers/{target}/{file_id}/{generation}")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";
let target = "<target>"; // Target, as named in the topology (`sim-1`).
let file_id = "<file_id>"; // On-board file identifier.
let generation = "1"; // Generation of the file.

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/transfers/{target}/{file_id}/{generation}"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "by": "string",
  "checksum": "string",
  "created_at": "string",
  "direction": "download",
  "file_id": "string",
  "file_type": "string",
  "generation": 0,
  "priority": 0,
  "reason": "string",
  "received": [
    [
      0
    ]
  ],
  "size": 0,
  "source": "string",
  "state": "REQUESTED",
  "target": "string",
  "updated_at": "string"
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/uploads

Store upload#

Store a content to upload

Stores the body (256 MiB at most) in the stellar_uploads object store under its SHA-256. The hash is the value of a file input of a run whose procedure uploads it (upload <input> to sat.files[x]).

Request body application/octet-streamrequired

The raw content, any bytes.

string

Responses

201Stored.application/json

hashrequired

string

Hexadecimal SHA-256: the value of a file input.

sizerequired

integer · int64

Size, in bytes.

≥ 0

413Content larger than 256 MiB.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/uploads" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @payload.bin

import requests

BASE_URL = "http://localhost:8080"

response = requests.post(
    f"{BASE_URL}/v1/uploads",
    data=open("payload.bin", "rb").read(),
    headers={"Content-Type": "application/octet-stream"},
)
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/uploads"))
    .header("Content-Type", "application/octet-stream")
    .body(std::fs::read("payload.bin")?)
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "hash": "string",
  "size": 0
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/transfers/watch

Watch transfers#

Watch the file transfers (WebSocket)

Sends every transfer, then each one that changes state or progresses.

Query parameters

target

string

Only those of this target.

Responses

101WebSocket: one Transfer per message.application/json

by

string

Who asked for it.

checksum

string

Checksum of the whole file, hexadecimal, as listed.

created_atrequired

string

Creation.

direction

TransferDirection

Direction.

file_idrequired

string

File identifier.

file_type

string

Type of the file (lttm…).

generationrequired

integer · uint64

Generation of the file.

≥ 0

priority

integer · int32

Priority: higher first.

default 0

reason

string

Why corrupted or superseded.

received

array of array of integer · uint64

Ranges received, [start, end) in bytes, sorted and disjoint.

sizerequired

integer · uint64

Size, in bytes.

≥ 0

source

string

Content uploaded: its hexadecimal SHA-256 in [UPLOADS_STORE].

state

TransferState

State.

targetrequired

string

Target.

updated_atrequired

string

Last change.

404Invalid target: api::invalid-target.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/transfers/watch"

import requests

BASE_URL = "http://localhost:8080"

response = requests.get(f"{BASE_URL}/v1/transfers/watch")
response.raise_for_status()

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/transfers/watch"))
    .send()
    .await?
    .error_for_status()?;

Response

{
  "by": "string",
  "checksum": "string",
  "created_at": "string",
  "direction": "download",
  "file_id": "string",
  "file_type": "string",
  "generation": 0,
  "priority": 0,
  "reason": "string",
  "received": [
    [
      0
    ]
  ],
  "size": 0,
  "source": "string",
  "state": "REQUESTED",
  "target": "string",
  "updated_at": "string"
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}