> ## 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.
# Import a state vector
> Import a state vector from an external source (OPM or SpaceX OPM format). For OPM format, the spacecraft can be auto-resolved from OBJECT_ID and OBJECT_NAME in the CCSDS metadata when spacecraftId is omitted. SpaceX OPM format requires an explicit spacecraftId. Creates a StateVector only, not an OrbitSolution.
## OpenAPI
````yaml https://api.valar.space/api-docs/mintlify post /operations/state-vectors/import
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
paths:
/operations/state-vectors/import:
post:
tags:
- State Vectors
summary: Import a state vector
description: >-
Import a state vector from an external source (OPM or SpaceX OPM
format). For OPM format, the spacecraft can be auto-resolved from
OBJECT_ID and OBJECT_NAME in the CCSDS metadata when spacecraftId is
omitted. SpaceX OPM format requires an explicit spacecraftId. Creates a
StateVector only, not an OrbitSolution.
operationId: importStateVector
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImportStateVectorRequest'
required: true
responses:
'201':
content:
application/json:
example:
id: SV-456
spacecraftId: 550e8400-e29b-41d4-a716-446655440000
spacecraftName: GS002
epoch: '2024-06-15T12:00:00Z'
position:
- 42164
- 0
- 0
velocity:
- 0
- 3.075
- 0
referenceFrame: EME2000
mass: 1500
originator: VALAR
creationDate: '2024-06-15T12:30:00Z'
sourceType: OPM_IMPORT
orbitSolutionId: null
hasCovariance: false
schema:
$ref: '#/components/schemas/StateVectorResponse'
description: State vector imported successfully
'400':
content:
application/json:
example:
timestamp: '2025-01-15T10:30:00.000Z'
status: 400
error: Bad Request
message: Validation failed
path: /operations/state-vectors/import
fieldErrors:
format: 'Format must be one of: OPM, SPACEX_OPM'
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Invalid request — parse error, unsupported format, or validation
failure
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/BearerTokenErrorResponse'
description: Not authenticated — missing or invalid bearer token
'403':
content:
application/json:
example:
timestamp: '2025-01-15T10:30:00.000Z'
status: 403
error: ACCESS_ERROR
message: Access denied
path: /operations/state-vectors/import
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Insufficient permissions
'404':
content:
application/json:
example:
timestamp: '2025-01-15T10:30:00.000Z'
status: 404
error: Not Found
message: No spacecraft found matching OPM identifiers
path: /operations/state-vectors/import
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Spacecraft not found (for explicit spacecraftId or auto-resolve
failure)
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error during import
components:
schemas:
ImportStateVectorRequest:
required:
- data
- format
type: object
properties:
data:
maxLength: 1048576
minLength: 0
type: string
description: >-
The raw state vector data in the specified format. For OPM: complete
CCSDS OPM message. For SPACEX_OPM: SpaceX-specific format. Maximum
size: 1MB.
format:
pattern: ^(OPM|SPACEX_OPM)$
type: string
description: Format of the state vector data
example: OPM
enum:
- OPM
- SPACEX_OPM
metadata:
$ref: '#/components/schemas/ImportMetadata'
spacecraftId:
type: string
description: >-
ID of the spacecraft to associate with the imported state vector.
Required for SPACEX_OPM format. For OPM format, if omitted, the
spacecraft is auto-resolved from OBJECT_ID and OBJECT_NAME in the
OPM metadata.
example: spacecraft-abc-123
description: Request for importing a single state vector
StateVectorResponse:
type: object
properties:
covariance:
$ref: '#/components/schemas/CovarianceDto'
creationDate:
type: string
description: >-
Creation timestamp when this state vector was created/imported in
ISO-8601 format
example: '2024-01-15T12:30:00Z'
epoch:
type: string
description: Epoch timestamp of the state vector in ISO-8601 format
example: '2024-01-15T12:00:00Z'
hasCovariance:
type: boolean
description: Whether covariance data is available for this state vector
example: true
id:
type: string
description: 'Unique identifier for the state vector (format: SV-{sequence})'
example: SV-123
keplerianElements:
$ref: '#/components/schemas/KeplerianElementsDto'
mass:
type: number
description: Spacecraft mass in kilograms
format: double
example: 1500
meanElementTheory:
type: string
description: >-
Theory used to produce meanElements. 'DSST' on success, null when
meanElements is null.
nullable: true
example: DSST
enum:
- DSST
meanElements:
$ref: '#/components/schemas/KeplerianElementsDto'
orbitSolutionId:
type: string
description: >-
ID of the associated OrbitSolution if this state vector was produced
by orbit determination. Null for imported state vectors.
nullable: true
example: GS002-559
originator:
type: string
description: Originator or source of this state vector data
example: VALAR
position:
type: array
description: Position vector [x, y, z] in kilometers
example:
- 42164
- 0
- 0
items:
type: number
description: Position vector [x, y, z] in kilometers
format: double
referenceFrame:
type: string
description: Reference frame of the state vector (e.g., EME2000, GCRF, TEME)
example: EME2000
sourceType:
type: string
description: >-
Source type indicating how this state vector was created. OPM_IMPORT
for imported OPMs, ORBIT_DETERMINATION for OD results, MANUAL for
manually entered.
example: OPM_IMPORT
enum:
- OPM_IMPORT
- ORBIT_DETERMINATION
- MANUAL
spacecraftId:
type: string
description: ID of the spacecraft this state vector belongs to
example: spacecraft-abc-123
spacecraftName:
type: string
description: Name of the spacecraft
example: GS002
velocity:
type: array
description: Velocity vector [vx, vy, vz] in km/s
example:
- 0
- 3.075
- 0
items:
type: number
description: Velocity vector [vx, vy, vz] in km/s
format: double
description: State vector representation with position, velocity, and metadata
ErrorResponse:
type: object
properties:
details:
type: object
additionalProperties:
type: object
description: Structured error details with scenario-specific context fields
nullable: true
description: Structured error details with scenario-specific context fields
nullable: true
error:
type: string
description: HTTP status reason phrase or error category
example: Bad Request
fieldErrors:
type: object
additionalProperties:
type: string
description: >-
Per-field validation error messages, present only for validation
errors
nullable: true
description: >-
Per-field validation error messages, present only for validation
errors
nullable: true
message:
type: string
description: Detailed error message
example: Validation failed
path:
type: string
description: The request path where the error occurred
example: /measurements
status:
type: integer
description: The HTTP status code
format: int32
example: 400
timestamp:
type: string
description: The timestamp when the error occurred
format: date-time
example: '2025-11-14T10:15:30.123Z'
BearerTokenErrorResponse:
type: object
properties:
error:
type: string
description: OAuth 2.0 error code
example: invalid_token
error_description:
type: string
description: Human-readable error description
example: An error occurred while attempting to decode the Jwt
description: OAuth 2.0 Bearer Token error response (RFC 6750)
ImportMetadata:
type: object
properties:
comments:
type: string
description: Optional comments about this import
mass:
minimum: 0.01
type: number
description: >-
Spacecraft mass in kg. Required for SPACEX_OPM format since it
doesn't include mass. For OPM format, this overrides the mass in the
file if provided.
format: double
example: 1500
originator:
type: string
description: >-
Originator of the state vector data. Overrides the originator from
the file if provided.
example: VALAR
referenceFrame:
type: string
description: >-
Reference frame override. If not provided, uses the frame from the
imported data.
example: EME2000
description: Optional metadata for state vector import
CovarianceDto:
type: object
properties:
matrix:
type: array
items:
type: array
items:
type: number
format: double
positionStdDev:
$ref: '#/components/schemas/PositionStdDevDto'
referenceFrame:
type: string
velocityStdDev:
$ref: '#/components/schemas/VelocityStdDevDto'
description: >-
State covariance data including 6x6 matrix and standard deviations. Null
if covariance is not available.
nullable: true
KeplerianElementsDto:
type: object
properties:
argumentOfPeriapsis:
type: number
format: double
eccentricity:
type: number
format: double
inclination:
type: number
format: double
raan:
type: number
format: double
semiMajorAxis:
type: number
format: double
trueAnomaly:
type: number
format: double
description: >-
Mean Keplerian orbital elements derived via DSST averaging of the
osculating state. Null when the DSST conversion fails (e.g., highly
perturbed orbits).
nullable: true
PositionStdDevDto:
type: object
properties:
x:
type: number
format: double
'y':
type: number
format: double
z:
type: number
format: double
VelocityStdDevDto:
type: object
properties:
vx:
type: number
format: double
vy:
type: number
format: double
vz:
type: number
format: double
securitySchemes:
apiKeyAuth:
description: 'API Key (format: vsp_sk_...)'
scheme: bearer
type: http
````