> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valar.space/llms.txt
> Use this file to discover all available pages before exploring further.
# Register a new spacecraft
> Creates a spacecraft.
## OpenAPI
````yaml https://api.valar.space/api-docs/mintlify post /operations/spacecraft
openapi: 3.0.1
info:
contact:
email: api@valar.space
name: Valar Space
url: https://valar.space
description: >-
Welcome to the documentation for the Valar Operations API, here are some
quick tips if you just landed!
- The top level elements are the
Resources accessible via the API and the different queries used to
interact with each resource via the appropriate HTTP method call.
-
You can expand each method to get further information on the expected input
parameters and the different responses that can be received.
- For
both the input parameters and responses, an Example is present for
clarification.
- For further details, the example snipped can be
switched to Schema view, where a detailed explanation of each element
can be found.
- The Try it out button can be used to call the
API directly from the documentation page, which allows for some easy testing
and also provides the equivalent 'curl' command line code for easy
portability of the call execution.
- Before starting, remember
to use the token endpoint and activate the token with the Authorize
button.
title: API Documentation
version: 1.0.0
servers:
- url: /
description: Default Server URL
- url: https://api.valar.space
description: API Server
security:
- apiKeyAuth: []
tags:
- description: >-
Operations for managing state vectors — listing, importing, exporting, and
deleting spacecraft state data
name: State Vectors
- description: Register, list, read, update, and manage the lifecycle of your spacecraft.
name: Spacecraft
- description: Manage the thrusters mounted on a spacecraft.
name: Thrusters
- description: Manage the payloads (sensors) mounted on a spacecraft.
name: Payloads
paths:
/operations/spacecraft:
post:
tags:
- Spacecraft
summary: Register a new spacecraft
description: Creates a spacecraft.
operationId: registerSpacecraft
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpacecraftRequest'
required: true
responses:
'201':
content:
'*/*':
schema:
$ref: '#/components/schemas/SpacecraftResponse'
description: Spacecraft successfully registered
'400':
content:
'*/*':
schema:
$ref: '#/components/schemas/SpacecraftResponse'
description: Invalid request data or validation failure
'401':
content:
'*/*':
schema:
$ref: '#/components/schemas/SpacecraftResponse'
description: Unauthorized - JWT token missing or invalid
'403':
content:
'*/*':
schema:
$ref: '#/components/schemas/SpacecraftResponse'
description: Forbidden - User lacks PERM_write:spacecraft permission
'409':
content:
'*/*':
schema:
$ref: '#/components/schemas/SpacecraftResponse'
description: Conflict - Duplicate spacecraft identifier
security:
- bearerAuth: []
components:
schemas:
CreateSpacecraftRequest:
required:
- absorption
- bodyShape
- dragArea
- dragCoefficient
- launchMass
- name
- reflectivityCoefficient
- specularReflection
- srpArea
type: object
properties:
absorption:
maximum: 1
exclusiveMaximum: false
minimum: 0
exclusiveMinimum: true
type: number
description: >-
Optical absorption coefficient α (dimensionless). Range (0.0, 1.0].
MLI default 0.4.
format: double
example: 0.4
bodyShape:
type: string
description: >-
Spacecraft body-shape primitive (DKR-2 §2.1). Determines which
dimension columns are populated.
example: BOX
enum:
- BOX
- REGULAR_PRISM
boxX:
maximum: 1000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: >-
Spacecraft box/bus X dimension (width) in meters. Required when
bodyShape=BOX.
format: double
example: 1.5
boxY:
maximum: 1000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: >-
Spacecraft box/bus Y dimension (height) in meters. Required when
bodyShape=BOX.
format: double
example: 1
boxZ:
maximum: 1000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: >-
Spacecraft box/bus Z dimension (length) in meters. Required when
bodyShape=BOX.
format: double
example: 2
color:
pattern: ^#?[0-9A-Fa-f]{6}$
type: string
description: 'Spacecraft color in hex format (with or without #)'
example: '#FF5733'
cosparId:
maxLength: 20
minLength: 0
pattern: ^\d{4}-\d{1,3}[A-HJ-NP-Z]{1,15}$
type: string
description: COSPAR international designator
example: 2024-001A
dragArea:
maximum: 10000
exclusiveMaximum: false
minimum: 0
exclusiveMinimum: true
type: number
description: Operator-typed drag cross-sectional area in m² (DKR-1 §3.6a).
format: double
example: 5
dragCoefficient:
maximum: 10
exclusiveMaximum: false
minimum: 0.1
exclusiveMinimum: false
type: number
description: 'Drag coefficient (typical values: 1.0-3.0)'
format: double
example: 2.2
dryMass:
maximum: 100000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: Mass without propellant in kg
format: double
example: 450
inertiaIxx:
type: number
description: >-
Principal moment of inertia about the body's primary principal axis
(kg·m²). Optional; null when inertia is not configured.
format: double
example: 1500
inertiaIyy:
type: number
description: >-
Principal moment of inertia about the body's secondary principal
axis (kg·m²). Optional; null when inertia is not configured.
format: double
example: 1700
inertiaIzz:
type: number
description: >-
Principal moment of inertia about the body's tertiary principal axis
(kg·m²). Optional; null when inertia is not configured.
format: double
example: 2100
launchMass:
maximum: 100000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: Total mass at launch in kg
format: double
example: 500
name:
maxLength: 100
minLength: 1
pattern: ^[a-zA-Z0-9\s_-]+$
type: string
description: Name of the spacecraft
example: Sentinel-1A
noradId:
maximum: 99999
minimum: 1
type: integer
description: NORAD catalog number
format: int32
example: 43013
panels:
maxItems: 8
minItems: 0
type: array
description: >-
Advanced-geometry solar panels attached to this spacecraft. 0..8
entries; per-panel validation cascades via @Valid.
nullable: true
items:
$ref: '#/components/schemas/PanelRequest'
payloads:
maxItems: 8
minItems: 0
type: array
description: >-
Payloads (sensors) attached to this spacecraft. 0..8 entries;
per-payload validation cascades via @Valid.
nullable: true
items:
$ref: '#/components/schemas/PayloadRequest'
prismAxis:
type: string
description: >-
Extrusion axis of the regular prism (DKR-1 §3.4). Defaults to Z.
Populated only when bodyShape = REGULAR_PRISM.
example: Z
enum:
- X
- 'Y'
- Z
prismDiameter:
maximum: 1000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: >-
Operator-supplied cross-section diameter D in meters (DKR-1 §3.4).
Converted to the canonical edge length per prismDiameterMeasure.
Populated only when bodyShape = REGULAR_PRISM; null otherwise.
format: double
example: 0.866025
prismDiameterMeasure:
type: string
description: >-
Whether prismDiameter is the inscribed (across-flats) or
circumscribed (across-vertices) circle diameter (DKR-1 §3.4).
Populated only when bodyShape = REGULAR_PRISM; null otherwise.
example: INSCRIBED
enum:
- INSCRIBED
- CIRCUMSCRIBED
prismHeightM:
maximum: 1000
exclusiveMaximum: false
minimum: 0.001
exclusiveMinimum: false
type: number
description: >-
Regular-prism height L along the extrusion axis in meters (DKR-1
§3.4). Populated only when bodyShape = REGULAR_PRISM; null
otherwise.
format: double
example: 1
prismSides:
maximum: 12
minimum: 3
type: integer
description: >-
Number of regular-polygon sides N (DKR-1 §3.4). Populated only when
bodyShape = REGULAR_PRISM; null otherwise. Range [3, 12].
format: int32
example: 6
reflectivityCoefficient:
maximum: 2
exclusiveMaximum: false
minimum: 1
exclusiveMinimum: false
type: number
description: >-
Reflectivity coefficient (1=pure absorber, 2=pure specular
reflector)
format: double
example: 1.5
specularReflection:
maximum: 1
exclusiveMaximum: true
minimum: 0
exclusiveMinimum: false
type: number
description: >-
Optical specular-reflection coefficient ρs (dimensionless). Range
[0.0, 1.0). MLI default 0.3. Energy conservation: absorption +
specularReflection <= 1.0.
format: double
example: 0.3
srpArea:
maximum: 10000
exclusiveMaximum: false
minimum: 0
exclusiveMinimum: true
type: number
description: >-
Operator-typed solar-radiation-pressure cross-sectional area in m²
(DKR-1 §3.6a).
format: double
example: 5
description: Request payload for creating a new spacecraft
SpacecraftResponse:
type: object
properties:
absorption:
type: number
description: Optical absorption coefficient α (dimensionless). Range (0.0, 1.0].
format: double
example: 0.4
bodyShape:
type: string
description: Body geometry primitive (BOX or REGULAR_PRISM).
example: BOX
enum:
- BOX
- REGULAR_PRISM
boxX:
type: number
description: Spacecraft box/bus X dimension (width) in meters
format: double
example: 1.5
boxY:
type: number
description: Spacecraft box/bus Y dimension (height) in meters
format: double
example: 1
boxZ:
type: number
description: Spacecraft box/bus Z dimension (length) in meters
format: double
example: 2
color:
type: string
description: Spacecraft color in hex format
example: '#FF5733'
cosparId:
type: string
description: COSPAR international designator
example: 2024-001A
createdAt:
type: string
description: Timestamp when the spacecraft was created
format: date-time
dragArea:
type: number
description: >-
Operator-typed drag cross-sectional area in m² (null for
pre-migration spacecraft)
format: double
example: 5
dragCoefficient:
type: number
description: Drag coefficient
format: double
example: 2.2
dryMass:
type: number
description: Mass without propellant in kg
format: double
example: 450
id:
type: string
description: Unique identifier of the spacecraft
example: 550e8400-e29b-41d4-a716-446655440000
inertiaIxx:
type: number
description: >-
Principal moment of inertia about the body's primary principal axis
(kg·m²). Optional; null when inertia is not configured.
format: double
example: 1500
inertiaIyy:
type: number
description: >-
Principal moment of inertia about the body's secondary principal
axis (kg·m²). Optional; null when inertia is not configured.
format: double
example: 1700
inertiaIzz:
type: number
description: >-
Principal moment of inertia about the body's tertiary principal axis
(kg·m²). Optional; null when inertia is not configured.
format: double
example: 2100
launchMass:
type: number
description: Total mass at launch in kg
format: double
example: 500
lifecycleStatus:
type: string
description: Lifecycle status of the spacecraft
example: Active
name:
type: string
description: Name of the spacecraft
example: Sentinel-1A
noradId:
type: integer
description: NORAD catalog number
format: int32
example: 43013
organizationId:
type: string
description: Organization ID that owns this spacecraft
example: VALAR
panels:
type: array
description: >-
Per-panel rows (0..8). Each entry carries dimensions, attachment
face, and orientation angles.
items:
$ref: '#/components/schemas/PanelResponse'
prismAxis:
type: string
description: >-
Extrusion axis of the regular prism (DKR-1 §3.4). Populated only
when bodyShape=REGULAR_PRISM; null otherwise.
example: Z
enum:
- X
- 'Y'
- Z
prismComplementaryDiameter:
type: number
description: >-
Cross-section diameter in the OTHER datum (the complement of
prismDiameterMeasure), computed from edge + sides (DKR-1 §3.4).
Populated only when bodyShape=REGULAR_PRISM; null otherwise.
format: double
example: 1
prismDiameter:
type: number
description: >-
Cross-section diameter in the operator's chosen datum
(prismDiameterMeasure), computed from edge + sides (DKR-1 §3.4).
Populated only when bodyShape=REGULAR_PRISM; null otherwise.
format: double
example: 0.866025
prismDiameterMeasure:
type: string
description: >-
Which diameter datum the operator used to size the cross-section
(DKR-1 §3.4). Populated only when bodyShape=REGULAR_PRISM; null
otherwise.
example: INSCRIBED
enum:
- INSCRIBED
- CIRCUMSCRIBED
prismEdgeM:
type: number
description: >-
Canonical regular-polygon edge length a in meters (DKR-1 §6) — the
persisted source-of-truth cross-section dimension. Populated only
when bodyShape=REGULAR_PRISM; null otherwise.
format: double
example: 0.5
prismHeightM:
type: number
description: >-
Regular-prism height L along the extrusion axis in meters. Populated
only when bodyShape=REGULAR_PRISM; null otherwise.
format: double
example: 1
prismSides:
type: integer
description: >-
Number of regular-polygon sides N (DKR-1 §3.4). Populated only when
bodyShape=REGULAR_PRISM; null otherwise.
format: int32
example: 6
reflectivityCoefficient:
type: number
description: Reflectivity coefficient
format: double
example: 1
specularReflection:
type: number
description: >-
Optical specular-reflection coefficient ρs (dimensionless). Range
[0.0, 1.0).
format: double
example: 0.3
srpArea:
type: number
description: >-
Operator-typed SRP cross-sectional area in m² (null for
pre-migration spacecraft)
format: double
example: 5
updatedAt:
type: string
description: Timestamp when the spacecraft was last updated
format: date-time
description: Response containing spacecraft details
PanelRequest:
required:
- absorption
- doubleSided
- lengthM
- mountAxisPreset
- mountPositionX
- mountPositionY
- mountPositionZ
- name
- rotationDeg
- specularReflection
- widthM
type: object
properties:
absorption:
maximum: 1
exclusiveMaximum: false
minimum: 0
exclusiveMinimum: false
type: number
description: >-
Per-panel optical absorption coefficient α (dimensionless). Range
[0.0, 1.0]. Energy conservation: absorption + specularReflection ≤
1.0.
format: double
example: 0.3
doubleSided:
type: boolean
description: >-
Whether the panel contributes drag / SRP area on both faces (DKR-1
§3.1). Required.
example: true
lengthM:
minimum: 0.001
exclusiveMinimum: false
type: number
description: Plate length (along the panel's local L axis) in meters. Required.
format: double
example: 2
mountAxisCustomX:
type: number
description: >-
X component of the custom mount-axis direction. Required and
non-zero in magnitude only when mountAxisPreset = CUSTOM; ignored
otherwise.
format: double
example: 0
mountAxisCustomY:
type: number
description: >-
Y component of the custom mount-axis direction. See
mountAxisCustomX.
format: double
example: 0
mountAxisCustomZ:
type: number
description: >-
Z component of the custom mount-axis direction. See
mountAxisCustomX.
format: double
example: 5
mountAxisPreset:
type: string
description: >-
Body-frame mount axis the panel is oriented along. One of the six
cardinal presets (PLUS_X/MINUS_X/PLUS_Y/MINUS_Y/PLUS_Z/MINUS_Z) or
CUSTOM (then mountAxisCustomX/Y/Z carry the direction).
example: PLUS_Z
enum:
- PLUS_X
- MINUS_X
- PLUS_Y
- MINUS_Y
- PLUS_Z
- MINUS_Z
- CUSTOM
mountPositionX:
type: number
description: >-
Mount-point X coordinate in the spacecraft body frame (meters).
Required; may be negative; no cap.
format: double
example: -1.5
mountPositionY:
type: number
description: >-
Mount-point Y coordinate in the spacecraft body frame (meters).
Required; may be negative; no cap.
format: double
example: 0
mountPositionZ:
type: number
description: >-
Mount-point Z coordinate in the spacecraft body frame (meters).
Required; may be negative; no cap.
format: double
example: 0.25
name:
maxLength: 100
minLength: 0
type: string
description: >-
Operator-facing panel name. Required, non-blank, ≤ 100 chars; unique
per spacecraft (case-insensitive).
example: Port array
rotationDeg:
maximum: 360
exclusiveMaximum: true
minimum: 0
exclusiveMinimum: false
type: number
description: >-
Rotation about the mount axis (degrees). Range [0°, 360°) half-open
— values at 360° are equivalent to 0° and are rejected so the wire
contract stays canonical.
format: double
example: 90
specularReflection:
maximum: 1
exclusiveMaximum: false
minimum: 0
exclusiveMinimum: false
type: number
description: >-
Per-panel optical specular-reflection coefficient ρs
(dimensionless). Range [0.0, 1.0]. Energy conservation: absorption +
specularReflection ≤ 1.0.
format: double
example: 0.2
widthM:
minimum: 0.001
exclusiveMinimum: false
type: number
description: Plate width (along the panel's local W axis) in meters. Required.
format: double
example: 1
description: One independent solar / radiator panel (DKR-1 §2).
nullable: true
PayloadRequest:
required:
- boresight
- fovShape
- name
- positionX
- positionY
- positionZ
type: object
properties:
boresight:
type: string
description: Body-frame boresight axis. One of X+, X-, Y+, Y-, Z+, Z-.
example: Z+
enum:
- X+
- X-
- Y+
- Y-
- Z+
- Z-
fovShape:
type: string
description: >-
Field-of-view shape primitive (CONICAL, RECTANGULAR, ELLIPTICAL,
POLYGON). Determines which conditional shape parameters are
required.
example: CONICAL
enum:
- CONICAL
- RECTANGULAR
- ELLIPTICAL
- POLYGON
halfAngleDeg:
maximum: 90
exclusiveMaximum: false
minimum: 0
exclusiveMinimum: true
type: number
description: >-
Cone half-angle in degrees (CONICAL only). Range (0°, 90°]; 90°
accepted.
format: double
example: 30
halfHeightDeg:
maximum: 90
exclusiveMaximum: true
minimum: 0
exclusiveMinimum: true
type: number
description: >-
FOV half-height in degrees (RECTANGULAR / ELLIPTICAL only). Range
(0°, 90°) strict.
format: double
example: 20
halfWidthDeg:
maximum: 90
exclusiveMaximum: true
minimum: 0
exclusiveMinimum: true
type: number
description: >-
FOV half-width in degrees (RECTANGULAR / ELLIPTICAL only). Range
(0°, 90°) strict.
format: double
example: 10
name:
maxLength: 100
minLength: 0
type: string
description: Operator-supplied payload name.
example: EO Camera
positionX:
type: number
description: Payload mounting position X in metres (body frame; may be negative).
format: double
example: 0.1
positionY:
type: number
description: Payload mounting position Y in metres (body frame; may be negative).
format: double
example: 0
positionZ:
type: number
description: Payload mounting position Z in metres (body frame; may be negative).
format: double
example: -0.2
radiusDeg:
maximum: 90
exclusiveMaximum: true
minimum: 0
exclusiveMinimum: true
type: number
description: >-
Polygon circumscribed (to-vertices) angular radius in degrees
(POLYGON only). Range (0°, 90°) strict. Datum =
OUTSIDE_CONE_TOUCHING_POLYGON_AT_VERTICES (DA-3).
format: double
example: 30
sides:
maximum: 1000
minimum: 3
type: integer
description: Number of polygon sides (POLYGON only). 3 ≤ N ≤ 1000.
format: int32
example: 6
description: >-
One payload (sensor): boresight axis + four-shape field of view (DKR-1
§3.3).
nullable: true
PanelResponse:
type: object
properties:
absorption:
type: number
description: Per-panel optical absorption coefficient α (dimensionless).
format: double
example: 0.3
derivedNormal:
$ref: '#/components/schemas/DerivedNormal'
doubleSided:
type: boolean
description: Whether the panel contributes drag / SRP area on both faces.
example: true
lengthM:
type: number
description: Plate length (along the panel's local L axis) in meters.
format: double
example: 2
mountAxisCustomX:
type: number
description: >-
X component of the custom mount-axis direction; null unless
mountAxisPreset = CUSTOM.
format: double
example: 0
mountAxisCustomY:
type: number
description: >-
Y component of the custom mount-axis direction; null unless
mountAxisPreset = CUSTOM.
format: double
example: 0
mountAxisCustomZ:
type: number
description: >-
Z component of the custom mount-axis direction; null unless
mountAxisPreset = CUSTOM.
format: double
example: 5
mountAxisPreset:
type: string
description: Body-frame mount axis the panel is oriented along.
example: PLUS_Z
enum:
- PLUS_X
- MINUS_X
- PLUS_Y
- MINUS_Y
- PLUS_Z
- MINUS_Z
- CUSTOM
mountPositionX:
type: number
description: Mount-point X coordinate in the spacecraft body frame (meters).
format: double
example: -1.5
mountPositionY:
type: number
description: Mount-point Y coordinate in the spacecraft body frame (meters).
format: double
example: 0
mountPositionZ:
type: number
description: Mount-point Z coordinate in the spacecraft body frame (meters).
format: double
example: 0.25
name:
type: string
description: Operator-facing panel name.
example: Port array
panelIndex:
type: integer
description: Zero-based panel slot index within the spacecraft.
format: int32
example: 0
rotationDeg:
type: number
description: Rotation about the mount axis (degrees). Range [0°, 360°).
format: double
example: 90
specularReflection:
type: number
description: >-
Per-panel optical specular-reflection coefficient ρs
(dimensionless).
format: double
example: 0.2
widthM:
type: number
description: Plate width (along the panel's local W axis) in meters.
format: double
example: 1
description: >-
One independent solar / radiator panel with its server-derived outward
normal (DKR-1 §2 / §3.1).
DerivedNormal:
type: object
properties:
x:
type: number
description: Body-frame X component.
format: double
example: 1
'y':
type: number
description: Body-frame Y component.
format: double
example: 0
z:
type: number
description: Body-frame Z component.
format: double
example: 0
description: A body-frame outward unit-normal triple {x, y, z}.
securitySchemes:
apiKeyAuth:
description: 'API Key (format: vsp_sk_...)'
scheme: bearer
type: http
````