{ "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!

  1. 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.
  2. You can expand each method to get further information on the expected input parameters and the different responses that can be received.
  3. For both the input parameters and responses, an Example is present for clarification.
  4. For further details, the example snipped can be switched to Schema view, where a detailed explanation of each element can be found.
  5. 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.
  6. Before starting, select Authorize and enter your API key. The key is sent as a bearer token in the Authorization header.
", "title" : "API Documentation", "version" : "1.0.0" }, "servers" : [ { "url" : "https://api.valar.space", "description" : "VALAR API Server" }, { "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" }, { "description" : "Maneuver API 2.0.0: create, read, edit, delete, import, and export spacecraft maneuvers.", "name" : "Maneuvers" } ], "paths" : { "/operations/maneuvers" : { "get" : { "operationId" : "getOperationsManeuvers", "parameters" : [ { "in" : "query", "name" : "spacecraftIds", "required" : true, "schema" : { "maxItems" : 50, "minItems" : 1, "type" : "array", "items" : { "type" : "string" } } }, { "in" : "query", "name" : "startDate", "required" : true, "schema" : { "type" : "string", "format" : "date-time" } }, { "in" : "query", "name" : "endDate", "required" : true, "schema" : { "type" : "string", "format" : "date-time" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListResponseManeuverResponse" } } }, "description" : "Wrapped maneuver list" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "List stored maneuvers", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" }, "post" : { "operationId" : "createOperationsManeuvers", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateManeuverRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateManeuverResponse" } } }, "description" : "Maneuvers created" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Duplicate identity or overlapping maneuver" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Create maneuvers atomically", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" } }, "/operations/maneuvers/export" : { "get" : { "description" : "Select IDs using exactly one spacecraftIds value and 1–100 maneuverIds, without time bounds; or select a range using 1–50 spacecraftIds and both startDate and endDate, without maneuverIds. endDate must be after startDate. spacecraftIds accepts repeated or comma-separated parameters. maneuverIds accepts repeated parameters only; commas are literal identity characters. Duplicate maneuverIds are invalid. One selected ID returns OCM; multiple IDs return ZIP. Range exports return OCM for one spacecraft and ZIP for multiple spacecraft. No request body is used.", "operationId" : "exportOperationsManeuvers", "parameters" : [ { "description" : "VALAR spacecraft IDs; repeated or comma-separated", "in" : "query", "name" : "spacecraftIds", "required" : true, "schema" : { "maxItems" : 50, "minItems" : 1, "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Stable maneuver IDs scoped to one spacecraft; repeat this parameter for each ID. Commas, spaces and Unicode are literal identity characters, not delimiters. Duplicate IDs are invalid.", "explode" : true, "in" : "query", "name" : "maneuverIds", "required" : false, "schema" : { "maxItems" : 100, "minItems" : 1, "uniqueItems" : true, "type" : "array", "items" : { "maxLength" : 63, "type" : "string" } }, "style" : "form" }, { "in" : "query", "name" : "startDate", "required" : false, "schema" : { "type" : "string", "format" : "date-time" } }, { "in" : "query", "name" : "endDate", "required" : false, "schema" : { "type" : "string", "format" : "date-time" } } ], "responses" : { "200" : { "content" : { "application/zip" : { "schema" : { "type" : "string", "format" : "byte" } }, "text/plain" : { "schema" : { "type" : "string", "format" : "byte" } } }, "description" : "OCM text or ZIP of OCMs" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid or ambiguous export selection" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Export stored maneuvers", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" } }, "/operations/maneuvers/import" : { "post" : { "operationId" : "importOperationsManeuvers", "parameters" : [ { "in" : "header", "name" : "X-Content-Hash", "required" : false, "schema" : { "type" : "string" } }, { "in" : "header", "name" : "X-Resolution-Fingerprint", "required" : false, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "spacecraftId", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "type" : "object", "properties" : { "files" : { "type" : "array", "items" : { "type" : "string", "format" : "binary" } } }, "required" : [ "files" ] } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ManeuverImportResultResponse" } } }, "description" : "All files imported" }, "207" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ManeuverImportResultResponse" } } }, "description" : "Per-file results; each file is atomic" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Import generic OCM records", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" } }, "/operations/maneuvers/{maneuverId}" : { "delete" : { "operationId" : "deleteOperationsManeuver", "parameters" : [ { "in" : "path", "name" : "maneuverId", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "204" : { "description" : "Maneuver deleted" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Delete a stored maneuver", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" }, "get" : { "operationId" : "getOperationsManeuver", "parameters" : [ { "in" : "path", "name" : "maneuverId", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StoredManeuverResponse" } } }, "description" : "Stored maneuver details" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Spacecraft reference or maneuver not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Read a complete stored maneuver", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" }, "put" : { "operationId" : "updateOperationsManeuver", "parameters" : [ { "in" : "path", "name" : "maneuverId", "required" : true, "schema" : { "type" : "string" } }, { "in" : "query", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateManeuverRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StoredManeuverResponse" } } }, "description" : "Updated stored maneuver" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Overlapping maneuver" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Replace a maneuver's editable fields", "tags" : [ "Maneuvers" ], "x-valar-contract-version" : "2.0.0" } }, "/operations/measurements" : { "get" : { "description" : "Retrieves paginated measurements with optional filtering by spacecraft, measurement type, date range, and outlier status. Results are sorted by epoch descending by default.", "operationId" : "getMeasurements", "parameters" : [ { "description" : "Start of time range (inclusive, ISO-8601)", "example" : "2025-01-01T00:00:00Z", "in" : "query", "name" : "startDate", "required" : true, "schema" : { "type" : "string", "format" : "date-time" } }, { "description" : "End of time range (inclusive, ISO-8601)", "example" : "2025-01-02T00:00:00Z", "in" : "query", "name" : "endDate", "required" : true, "schema" : { "type" : "string", "format" : "date-time" } }, { "description" : "Filter by spacecraft identifiers (ID, name, NORAD, or COSPAR). Between 1 and 100 non-blank values; omit the parameter entirely for an unfiltered read (an explicitly empty selection is a 400 VALIDATION_ERROR).", "in" : "query", "name" : "spacecraftIds", "required" : false, "schema" : { "maxItems" : 100, "minItems" : 1, "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Filter by measurement types", "in" : "query", "name" : "measurementTypes", "required" : false, "schema" : { "type" : "array", "items" : { "type" : "string", "enum" : [ "RANGE", "RADEC", "AZEL", "DOPPLER", "PV" ] } } }, { "description" : "Include measurements flagged as outliers (default: false)", "example" : false, "in" : "query", "name" : "includeOutliers", "required" : false, "schema" : { "type" : "boolean", "default" : false } }, { "in" : "query", "name" : "pageable", "required" : true, "schema" : { "$ref" : "#/components/schemas/Pageable" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ReferenceResolvingPaginatedResponseUnifiedMeasurementDto" } } }, "description" : "Successfully retrieved measurements" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Validation failed", "path" : "/operations/measurements", "fieldErrors" : { "startDate" : "must not be null" } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request parameters" }, "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/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Insufficient permissions" }, "500" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Query measurements with pagination and filtering", "tags" : [ "Measurements" ] }, "post" : { "description" : "Upload one or more measurement files for asynchronous processing. Supported formats: TDM (Tracking Data Message), SP3 (Standard Product 3), and OEM (Orbit Ephemeris Message). Each file is validated synchronously and then queued as a background job for full processing. The response includes per-file results with job IDs for tracking processing status.", "operationId" : "uploadMeasurementFiles", "parameters" : [ { "description" : "SHA-256 content hash from a prior /imports/inspect call. When present and exactly one file is uploaded, the server re-verifies this hash against the uploaded content and returns 409 IMPORT_STALE_PREVIEW on mismatch. Ignored (with a DEBUG log) for multi-file batch uploads, since the header cannot unambiguously bind to one of several files.", "in" : "header", "name" : "X-Content-Hash", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "multipart/form-data" : { "schema" : { "type" : "object", "properties" : { "files" : { "type" : "array", "description" : "Measurement files to upload (TDM, SP3, OEM formats)", "items" : { "type" : "string", "format" : "binary" } } }, "required" : [ "files" ] } } } }, "responses" : { "202" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchUploadResponse" } } }, "description" : "Files accepted for processing" }, "207" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchUploadResponse" } } }, "description" : "Partial failure: at least one file failed; see results[] for per-file outcomes" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "No files provided", "path" : "/operations/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "No files provided or invalid request" }, "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/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Insufficient permissions" }, "409" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 409, "error" : "IMPORT_STALE_PREVIEW", "code" : "import.commit.preview.stale", "message" : "Content hash mismatch: the preview you inspected is stale", "path" : "/operations/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Stale preview: the X-Content-Hash header does not match the uploaded content" }, "413" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 413, "error" : "Payload Too Large", "message" : "File size exceeds the maximum allowed limit", "path" : "/operations/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "File size exceeds the maximum allowed limit" }, "500" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/measurements" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Upload measurement files", "tags" : [ "Measurements" ] } }, "/operations/measurements/by-file" : { "delete" : { "description" : "Permanently deletes all measurements for a spacecraft from a specific source file. This is useful when an uploaded file contains incorrect data. WARNING: This operation cannot be undone. Returns 200 with deletedCount=0 if no matching measurements are found.", "operationId" : "deleteByFile", "parameters" : [ { "description" : "Spacecraft identifier", "example" : "SAT-1", "in" : "query", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Source file name to delete measurements from", "example" : "tracking_data_2025-01-15.tdm", "in" : "query", "name" : "file", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DeleteByFileResponse" } } }, "description" : "Measurements deleted successfully" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Validation failed", "path" : "/operations/measurements/by-file", "fieldErrors" : { "spacecraftId" : "spacecraftId is required" } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request — missing required parameters" }, "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/measurements/by-file" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Insufficient permissions — requires write:tracking authority" }, "500" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/measurements/by-file" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Delete measurements by source file", "tags" : [ "Measurements" ] } }, "/operations/measurements/outliers" : { "patch" : { "description" : "Performs a bulk update of the outlier status on multiple measurements simultaneously. Maximum 1000 measurement IDs per request. Non-existent IDs are silently ignored. The returned count reflects only actually updated measurements.", "operationId" : "bulkMarkOutlier", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkMarkOutlierRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkOutlierResponse" } } }, "description" : "Bulk operation completed successfully" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Validation failed", "path" : "/operations/measurements/outliers", "fieldErrors" : { "measurementIds" : "must not be empty" } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request — empty list, exceeds 1000 IDs, or missing fields" }, "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/measurements/outliers" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Insufficient permissions — requires write:tracking authority" }, "500" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/measurements/outliers" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Bulk mark or unmark measurements as outliers by ID list", "tags" : [ "Measurements" ] } }, "/operations/measurements/outliers/by-file" : { "patch" : { "description" : "Performs a bulk update of the outlier status on all measurements originating from a specific source file. File name matching is exact and case-sensitive. The returned count reflects all matching measurements updated within the current tenant.", "operationId" : "bulkMarkOutlierByFile", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkMarkOutlierByFileRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkOutlierResponse" } } }, "description" : "Bulk operation completed successfully" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Validation failed", "path" : "/operations/measurements/outliers/by-file", "fieldErrors" : { "fileName" : "must not be blank" } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request — blank or invalid file name" }, "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/measurements/outliers/by-file" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Insufficient permissions — requires write:tracking authority" }, "500" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/measurements/outliers/by-file" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Bulk mark or unmark measurements as outliers by source file", "tags" : [ "Measurements" ] } }, "/operations/spacecraft" : { "get" : { "description" : "Retrieves a paginated list of spacecraft for the current tenant.", "operationId" : "listSpacecraft", "parameters" : [ { "description" : "Lifecycle status filter (Active or Archived)", "example" : "Active", "in" : "query", "name" : "status", "required" : false, "schema" : { "type" : "string" } }, { "description" : "Include archived spacecraft when status is absent (true=all, false=active-only). Ignored when status is set.", "example" : false, "in" : "query", "name" : "includeArchived", "required" : false, "schema" : { "type" : "boolean" } }, { "description" : "Exact NORAD catalog number lookup filter. Exact string match — not numerically normalised (leading zeros are significant).", "example" : 25544, "in" : "query", "name" : "noradId", "required" : false, "schema" : { "maxLength" : 63, "minLength" : 0, "type" : "string" } }, { "description" : "Exact COSPAR international designator lookup filter.", "example" : "1998-067A", "in" : "query", "name" : "cosparId", "required" : false, "schema" : { "maxLength" : 20, "minLength" : 0, "type" : "string" } }, { "description" : "Exact, case-insensitive spacecraft name lookup filter.", "example" : "ISS-Module-A", "in" : "query", "name" : "name", "required" : false, "schema" : { "maxLength" : 100, "minLength" : 0, "type" : "string" } }, { "description" : "Exact caller-assigned external-key lookup filter.", "example" : "PARTNER-SAT-001", "in" : "query", "name" : "externalKey", "required" : false, "schema" : { "maxLength" : 64, "minLength" : 0, "type" : "string" } }, { "in" : "query", "name" : "pageable", "required" : true, "schema" : { "$ref" : "#/components/schemas/Pageable" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaginatedResponseSpacecraftSummary" } } }, "description" : "Spacecraft list retrieved successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request parameters (e.g. unsupported sort field)" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_read:spacecraft permission" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "List spacecraft", "tags" : [ "Spacecraft" ] }, "post" : { "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" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Register a new spacecraft", "tags" : [ "Spacecraft" ] } }, "/operations/spacecraft/{id}" : { "get" : { "description" : "Retrieves a spacecraft by its canonical UUID id. A non-UUID value (NORAD, COSPAR, or name) is rejected with 400 VALIDATION_ERROR before resolution. Returns 404 if no such spacecraft exists.", "operationId" : "getSpacecraft", "parameters" : [ { "description" : "Spacecraft identifier (UUID)", "example" : "3fa85f64-5717-4562-b3fc-2c963f66afa6", "in" : "path", "name" : "id", "required" : true, "schema" : { "pattern" : "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SpacecraftResponse" } } }, "description" : "Spacecraft retrieved successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid spacecraft ID: supply a canonical UUID" }, "401" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "*/*" : { "schema" : { "type" : "object" } } }, "description" : "Forbidden - User lacks PERM_read:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Spacecraft not found (SC-4040)" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Get spacecraft by UUID", "tags" : [ "Spacecraft" ] }, "patch" : { "description" : "Updates only the provided fields of a spacecraft resolved strictly by id. Returns 404 if it does not exist.", "operationId" : "partialUpdateOperationsSpacecraft", "parameters" : [ { "description" : "Spacecraft identifier (UUID)", "example" : "3fa85f64-5717-4562-b3fc-2c963f66afa6", "in" : "path", "name" : "id", "required" : true, "schema" : { "pattern" : "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateSpacecraftRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/SpacecraftResponse" } } }, "description" : "Spacecraft updated successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request data or validation failure" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Spacecraft not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Partially update a spacecraft", "tags" : [ "Spacecraft" ] } }, "/operations/spacecraft/{id}/lifecycle" : { "put" : { "description" : "Updates the lifecycle status (Active or Archived) of a spacecraft resolved strictly by id. Returns 404 if it does not exist.", "operationId" : "updateOperationsSpacecraftLifecycle", "parameters" : [ { "description" : "Spacecraft identifier", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LifecycleUpdateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/SpacecraftResponse" } } }, "description" : "Lifecycle status updated successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid lifecycle status value" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Spacecraft not found" }, "409" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TaskDeletionConflictResponse" } } }, "description" : "Archive gated on task-deletion confirmation — body carries the taskCount of scheduled tasks the archive would permanently delete" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Update a spacecraft lifecycle status", "tags" : [ "Spacecraft" ] } }, "/operations/spacecraft/{spacecraftId}/payloads" : { "get" : { "description" : "Retrieves all payloads for a parent spacecraft resolved strictly by id, ordered by payloadIndex ascending. Returns 404 if the parent spacecraft does not exist.", "operationId" : "listOperationsPayloads", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListResponsePayloadResponse" } } }, "description" : "Payloads retrieved successfully" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_read:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Parent spacecraft not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "List payloads for a spacecraft", "tags" : [ "Payloads" ] }, "post" : { "description" : "Adds a payload under a parent spacecraft resolved strictly by id. The server assigns the lowest-free slot index [0,7]; the 9th sensor is refused with 422 PAYLOAD_LIMIT_EXCEEDED. Returns 404 if the parent spacecraft does not exist.", "operationId" : "createOperationsPayload", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PayloadRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PayloadResponse" } } }, "description" : "Payload added successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request data" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Parent spacecraft not found" }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Payload limit exceeded (8-sensor cap)" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Add a payload", "tags" : [ "Payloads" ] } }, "/operations/spacecraft/{spacecraftId}/payloads/{payloadId}" : { "delete" : { "description" : "Removes a payload reached only through the parent's collection; the freed slot index is left as a gap (never repacked). Returns a uniform 404 for any miss vector.", "operationId" : "deleteOperationsPayload", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Payload id", "in" : "path", "name" : "payloadId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "204" : { "description" : "Payload removed successfully" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Payload not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Remove a payload", "tags" : [ "Payloads" ] }, "get" : { "description" : "Retrieves a payload reached only through the parent's collection. Returns a uniform 404 PAYLOAD_NOT_FOUND for an unknown id / foreign-tenant / wrong-parent (indistinguishable).", "operationId" : "getOperationsPayload", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Payload id", "in" : "path", "name" : "payloadId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PayloadResponse" } } }, "description" : "Payload retrieved successfully" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_read:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Payload not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Get a payload by id", "tags" : [ "Payloads" ] }, "patch" : { "description" : "Updates only the provided scalars of a payload in place (the UUID is never re-minted). The FOV group is an atomic replace: restate fovShape to change any FOV param; a lone FOV param without fovShape is a 400. Returns a uniform 404 for any miss vector. A genuine change to this payload's offNadirAlongTrackDeg or offNadirCrossTrackDeg field auto-mints a new slew-envelope revision as a same-transaction side effect. A mint failure over frame/attitude interpretability still rolls back the entire PATCH, so the payload's scalar fields revert to their pre-PATCH persisted values; a mint refused only because the payload's own aperture is non-isotropic does NOT roll back — the scalar edit still commits, and the rejection surfaces later via the affected AOI opportunities' own off-nadir disclosure rather than in this response.", "operationId" : "updateOperationsPayload", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Payload id", "in" : "path", "name" : "payloadId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdatePayloadRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PayloadResponse" } } }, "description" : "Payload updated successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request data" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Payload not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Partially update a payload", "tags" : [ "Payloads" ] } }, "/operations/spacecraft/{spacecraftId}/thrusters" : { "get" : { "description" : "Retrieves all thrusters for a parent spacecraft resolved strictly by id. Each type is rendered UPPER_CASE (DT-17). Returns 404 if the parent spacecraft does not exist.", "operationId" : "listOperationsThrusters", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListResponseEnvThrusterResponse" } } }, "description" : "Thrusters retrieved successfully" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_read:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Parent spacecraft not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "List thrusters for a spacecraft", "tags" : [ "Thrusters" ] }, "post" : { "description" : "Creates a thruster under a parent spacecraft resolved strictly by id. Type is auto-computed from ISP and rendered UPPER_CASE (DT-17). Returns 404 if the parent spacecraft does not exist.", "operationId" : "createOperationsThruster", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateThrusterRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EnvThrusterResponse" } } }, "description" : "Thruster created successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request data or duplicate thruster name" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Parent spacecraft not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Create a thruster", "tags" : [ "Thrusters" ] } }, "/operations/spacecraft/{spacecraftId}/thrusters/{thrusterId}" : { "delete" : { "description" : "Deletes a thruster resolved strictly by id. Returns 404 if it does not exist.", "operationId" : "deleteOperationsThruster", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Thruster id", "in" : "path", "name" : "thrusterId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "204" : { "description" : "Thruster deleted successfully" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Thruster not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Delete a thruster", "tags" : [ "Thrusters" ] }, "get" : { "description" : "Retrieves a thruster resolved strictly by id. Type is rendered UPPER_CASE (DT-17). Returns 404 if it does not exist.", "operationId" : "getOperationsThruster", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Thruster id", "in" : "path", "name" : "thrusterId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EnvThrusterResponse" } } }, "description" : "Thruster retrieved successfully" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_read:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Thruster not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Get a thruster by id", "tags" : [ "Thrusters" ] }, "patch" : { "description" : "Updates only the provided fields of a thruster resolved strictly by id. Type is re-computed from ISP and rendered UPPER_CASE (DT-17). Returns 404 if it does not exist.", "operationId" : "updateOperationsThruster", "parameters" : [ { "description" : "Parent spacecraft id", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Thruster id", "in" : "path", "name" : "thrusterId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateThrusterRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EnvThrusterResponse" } } }, "description" : "Thruster updated successfully" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request data or duplicate thruster name" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Unauthorized - JWT token missing or invalid" }, "403" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Forbidden - User lacks PERM_write:spacecraft permission" }, "404" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Thruster not found" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Partially update a thruster", "tags" : [ "Thrusters" ] } }, "/operations/spacecraft/{spacecraftId}/tle" : { "get" : { "description" : "Returns an own-computed TLE at the explicit requested epoch. Uses the latest eligible stored state by epoch: manual/imported states or accepted converged orbit solutions. Propagates with the existing accurate force model and applicable maneuvers, then fits a single-state TLE. This does not retrieve provider TLEs, select a historical state, persist a resource, or start a background job. Required spacecraft force-model configuration must be present. Assigned numeric catalogue IDs through 339999 can be serialized (Alpha-5 above 99999); larger IDs are rejected, never truncated. A missing NORAD ID retains the generator's 99999 placeholder. Requires a valid API key with read:ephemeris permission and access to the spacecraft. Success is text/plain only; an unsupported or malformed Accept header returns 406. Request and generation failures use JSON error envelopes even when Accept is text/plain. Missing credentials or malformed bearer tokens may instead receive an empty 401 with WWW-Authenticate: Bearer. No receiver compatibility or orbit accuracy guarantee is implied.", "operationId" : "generateOperationsTle", "parameters" : [ { "description" : "Canonical spacecraft ID from the spacecraft API; names, NORAD and COSPAR identifiers are not accepted", "example" : "550e8400-e29b-41d4-a716-446655440000", "in" : "path", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Required target epoch as an ISO-8601 instant with timezone; no implicit default", "example" : "2026-09-22T12:00:00Z", "in" : "query", "name" : "epoch", "required" : true, "schema" : { "type" : "string", "format" : "date-time" } } ], "responses" : { "200" : { "content" : { "text/plain" : { "schema" : { "type" : "string" } } }, "description" : "Two TLE lines separated by a newline, without a name line" }, "400" : { "content" : { "application/json" : { "examples" : { "missingEpoch" : { "description" : "missingEpoch", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 400, "error" : "VALIDATION_ERROR", "message" : "Required parameter 'epoch' of type 'Instant' is missing", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Missing or invalid epoch, invalid source state, missing force-model configuration, unsupported catalogue ID, or propagation failure" }, "401" : { "content" : { "application/json" : { "examples" : { "invalidApiKey" : { "description" : "invalidApiKey", "summary" : "Rejected API-key credentials; security entry-point 401 responses can have no body", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 401, "error" : "Unauthorized", "message" : "Invalid API key", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Missing, invalid, expired or disabled credentials. API-key rejections return JSON; missing credentials or malformed bearer tokens may return an empty body with WWW-Authenticate: Bearer" }, "403" : { "content" : { "application/json" : { "examples" : { "missingPermission" : { "description" : "missingPermission", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 403, "error" : "ACCESS_ERROR", "message" : "Access denied", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Key grant, IP allowlist or read:ephemeris permission is insufficient" }, "404" : { "content" : { "application/json" : { "examples" : { "spacecraftNotFound" : { "description" : "spacecraftNotFound", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 404, "error" : "SC-4040", "message" : "Spacecraft with identifier '550e8400-e29b-41d4-a716-446655440000' not found", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Spacecraft is unknown or inaccessible" }, "406" : { "content" : { "application/json" : { "examples" : { "unsupportedAccept" : { "description" : "unsupportedAccept", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 406, "error" : "Not Acceptable", "message" : "Accept header is malformed or does not allow a supported response media type", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Accept header is malformed or does not allow text/plain; errors are returned as JSON" }, "422" : { "content" : { "application/json" : { "examples" : { "degenerateState" : { "description" : "degenerateState", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 422, "error" : "COMPUTE_STATE_INSIDE_ELLIPSOID", "message" : "The requested computation resolved a state vector inside the Earth ellipsoid (sub-surface). Verify the spacecraft's state vector, or shorten the propagation window.", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } }, "missingOrbitalState" : { "description" : "missingOrbitalState", "value" : { "timestamp" : "2026-09-24T12:00:00Z", "status" : 422, "error" : "ORBITAL_STATE_NOT_FOUND", "message" : "No orbital state found for spacecraft 'Geosat-2'. Please upload ephemeris data or propagate from a TLE before plotting.", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Missing eligible orbital state, physically degenerate or numerically unrepresentable orbital input" }, "500" : { "content" : { "application/json" : { "examples" : { "unexpectedFailure" : { "description" : "unexpectedFailure", "value" : { "timestamp" : "2026-09-22T12:00:00Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/spacecraft/550e8400-e29b-41d4-a716-446655440000/tle" } } }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Unexpected generation failure" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Generate a fitted TLE", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors" : { "get" : { "description" : "Retrieves a paginated list of state vectors for the specified spacecraft(s), with optional date range filtering. The spacecraftId parameter may be repeated to query multiple spacecraft in a single call (e.g. ?spacecraftId=A&spacecraftId=B); results are merged into a single paginated set. Results are sorted by epoch descending by default. Empty results return 200 with an empty page.", "operationId" : "getStateVectors", "parameters" : [ { "description" : "Spacecraft identifier(s) to filter state vectors by. Required; may be repeated to query multiple spacecraft in a single call (e.g. ?spacecraftId=A&spacecraftId=B), in which case results are merged into a single paginated set sorted by epoch desc.", "example" : "550e8400-e29b-41d4-a716-446655440000", "in" : "query", "name" : "spacecraftId", "required" : true, "schema" : { "maxItems" : 50, "minItems" : 1, "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Start of date range filter (inclusive, ISO-8601)", "example" : "2025-01-01T00:00:00Z", "in" : "query", "name" : "startDate", "required" : false, "schema" : { "type" : "string", "format" : "date-time" } }, { "description" : "End of date range filter (inclusive, ISO-8601)", "example" : "2025-01-02T00:00:00Z", "in" : "query", "name" : "endDate", "required" : false, "schema" : { "type" : "string", "format" : "date-time" } }, { "in" : "query", "name" : "pageable", "required" : true, "schema" : { "$ref" : "#/components/schemas/Pageable" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ReferenceResolvingPaginatedResponse" } } }, "description" : "Successfully retrieved state vectors" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Required parameter 'spacecraftId' is not present", "path" : "/operations/state-vectors" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request parameters" }, "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" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Insufficient permissions" }, "500" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 500, "error" : "Internal Server Error", "message" : "An unexpected error occurred", "path" : "/operations/state-vectors" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "List state vectors for one or more spacecraft", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors/import" : { "post" : { "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.0, 0.0 ], "velocity" : [ 0.0, 3.075, 0.0 ], "referenceFrame" : "EME2000", "mass" : 1500.0, "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" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Import a state vector", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors/latest" : { "get" : { "description" : "Retrieves the most recent state vector for a spacecraft. By default, only converged state vectors are returned (imports are always valid, OD results only if converged). Set includeNonConverged=true to include all state vectors.", "operationId" : "getLatestStateVector", "parameters" : [ { "description" : "Spacecraft identifier", "example" : "550e8400-e29b-41d4-a716-446655440000", "in" : "query", "name" : "spacecraftId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Include non-converged OD results (default: false)", "example" : false, "in" : "query", "name" : "includeNonConverged", "required" : false, "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "application/json" : { "example" : { "id" : "SV-123", "spacecraftId" : "550e8400-e29b-41d4-a716-446655440000", "spacecraftName" : "GS002", "epoch" : "2024-06-15T12:00:00Z", "position" : [ 42164.0, 0.0, 0.0 ], "velocity" : [ 0.0, 3.075, 0.0 ], "referenceFrame" : "EME2000", "mass" : 1500.0, "originator" : "VALAR", "creationDate" : "2024-06-15T12:30:00Z", "sourceType" : "OPM_IMPORT", "orbitSolutionId" : null, "hasCovariance" : false }, "schema" : { "$ref" : "#/components/schemas/StateVectorResponse" } } }, "description" : "Successfully retrieved the latest state vector" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Required parameter 'spacecraftId' is not present", "path" : "/operations/state-vectors/latest" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request parameters" }, "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/latest" }, "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 state vector found for spacecraft", "path" : "/operations/state-vectors/latest" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "No state vector found for spacecraft" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Get the latest state vector for a spacecraft", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors/{id}" : { "delete" : { "description" : "Deletes a state vector by its unique identifier. Deletion is not allowed if the state vector is linked to an orbit solution (returns 409 Conflict).", "operationId" : "deleteStateVector", "parameters" : [ { "description" : "State vector display ID to delete", "example" : "SV-123", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "204" : { "description" : "State vector deleted successfully" }, "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/{id}" }, "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" : "StateVector not found with id: SV-999", "path" : "/operations/state-vectors/SV-999" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "State vector not found" }, "409" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 409, "error" : "Conflict", "message" : "Cannot delete state vector that is linked to an orbit solution", "path" : "/operations/state-vectors/SV-123" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "State vector is linked to an orbit solution and cannot be deleted" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Delete a state vector", "tags" : [ "State Vectors" ] }, "get" : { "description" : "Retrieves a specific state vector by its unique identifier.", "operationId" : "getStateVectorById", "parameters" : [ { "description" : "State vector display ID", "example" : "SV-123", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "example" : { "id" : "SV-123", "spacecraftId" : "550e8400-e29b-41d4-a716-446655440000", "spacecraftName" : "GS002", "epoch" : "2024-06-15T12:00:00Z", "position" : [ 42164.0, 0.0, 0.0 ], "velocity" : [ 0.0, 3.075, 0.0 ], "referenceFrame" : "EME2000", "mass" : 1500.0, "originator" : "VALAR", "creationDate" : "2024-06-15T12:30:00Z", "sourceType" : "OPM_IMPORT", "orbitSolutionId" : null, "hasCovariance" : false }, "schema" : { "$ref" : "#/components/schemas/StateVectorResponse" } } }, "description" : "Successfully retrieved the state vector" }, "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/{id}" }, "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" : "StateVector not found with id: SV-999", "path" : "/operations/state-vectors/SV-999" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "State vector not found" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal server error" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Get a state vector by ID", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors/{id}/export-omm" : { "get" : { "description" : "Export a state vector in CCSDS OMM v2.0 format with mean Keplerian elements. Uses DSST (Draper Semi-analytical Satellite Theory) for osculating-to-mean element conversion.", "operationId" : "exportOmm", "parameters" : [ { "description" : "State vector display ID", "example" : "SV-123", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Time system for OMM epoch timestamp", "example" : "UTC", "in" : "query", "name" : "timeSystem", "required" : false, "schema" : { "type" : "string", "default" : "UTC", "enum" : [ "UTC", "TAI", "TT", "TDB", "TCG", "TCB", "GPS" ] } }, { "description" : "Reference frame for mean orbital elements", "example" : "GCRF", "in" : "query", "name" : "referenceFrame", "required" : false, "schema" : { "type" : "string", "default" : "GCRF", "enum" : [ "GCRF", "EME2000", "ITRF", "TOD", "MOD", "TEME" ] } }, { "description" : "Epoch for OMM generation (ISO-8601). Defaults to state vector epoch.", "example" : "2024-01-01T00:00:00Z", "in" : "query", "name" : "epoch", "required" : false, "schema" : { "type" : "string", "format" : "date-time" } } ], "responses" : { "200" : { "content" : { "text/plain" : { "example" : "CCSDS_OMM_VERS = 2.0\nCREATION_DATE = 2024-06-15T12:30:00\nORIGINATOR = VALAR\n...", "schema" : { "type" : "string" } } }, "description" : "OMM file generated successfully" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Invalid OMM generation parameters", "path" : "/operations/state-vectors/{id}/export-omm" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request parameters or validation errors" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Not authenticated — missing or invalid bearer token" }, "403" : { "content" : { "application/json" : { "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" : "StateVector not found with id: SV-999", "path" : "/operations/state-vectors/SV-999/export-omm" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "State vector not found" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal error during OMM generation" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Export a state vector as OMM", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors/{id}/export-opm" : { "get" : { "description" : "Export a state vector in CCSDS OPM v2.0 format. Optionally includes covariance data if available.", "operationId" : "exportOpm", "parameters" : [ { "description" : "State vector display ID", "example" : "SV-123", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Include covariance data in OPM output (default: false)", "example" : false, "in" : "query", "name" : "includeCovariance", "required" : false, "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "text/plain" : { "example" : "CCSDS_OPM_VERS = 2.0\nCREATION_DATE = 2024-06-15T12:30:00\nORIGINATOR = VALAR\n...", "schema" : { "type" : "string" } } }, "description" : "OPM file generated successfully" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "VALIDATION_ERROR", "message" : "Covariance data is not available for this state vector", "path" : "/operations/state-vectors/{id}/export-opm" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Covariance requested but not available for this state vector" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Not authenticated — missing or invalid bearer token" }, "403" : { "content" : { "application/json" : { "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" : "StateVector not found with id: SV-999", "path" : "/operations/state-vectors/SV-999/export-opm" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "State vector not found" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal error during OPM generation" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Export a state vector as OPM", "tags" : [ "State Vectors" ] } }, "/operations/state-vectors/{id}/generate-oem" : { "post" : { "description" : "Generate CCSDS OEM v2.0 format ephemerides from a state vector with specified time range, reference frame, time system, and optional covariance propagation. Maximum time span is 30 days.", "operationId" : "generateOem", "parameters" : [ { "description" : "State vector display ID", "example" : "SV-123", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OemGenerationRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "text/plain" : { "example" : "CCSDS_OEM_VERS = 2.0\nCREATION_DATE = 2024-06-15T12:30:00\nORIGINATOR = VALAR\n...", "schema" : { "type" : "string" } } }, "description" : "OEM file generated successfully" }, "400" : { "content" : { "application/json" : { "example" : { "timestamp" : "2025-01-15T10:30:00.000Z", "status" : 400, "error" : "Bad Request", "message" : "Time span cannot exceed 30 days", "path" : "/operations/state-vectors/{id}/generate-oem" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Invalid request parameters or validation errors" }, "401" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BearerTokenErrorResponse" } } }, "description" : "Not authenticated — missing or invalid bearer token" }, "403" : { "content" : { "application/json" : { "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" : "StateVector not found with id: SV-999", "path" : "/operations/state-vectors/SV-999/generate-oem" }, "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "State vector not found" }, "422" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Orbit is stale (ORBIT_STALE) — the generate-oem carve-out keeps its 422 and is never acknowledged" }, "500" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponse" } } }, "description" : "Internal error during OEM generation" } }, "security" : [ { "apiKeyAuth" : [ ] } ], "summary" : "Generate OEM from a state vector", "tags" : [ "State Vectors" ] } } }, "components" : { "schemas" : { "AmbiguousTargetDetail" : { "type" : "object", "properties" : { "candidates" : { "type" : "array", "description" : "The candidate spacecraft that matched", "items" : { "$ref" : "#/components/schemas/TargetCandidate" } }, "identifier" : { "type" : "string", "description" : "The ambiguous identifier", "example" : "52771" } }, "description" : "Detail for an ambiguous target resolution", "nullable" : true }, "BatchUploadResponse" : { "type" : "object", "properties" : { "failureCount" : { "type" : "integer", "description" : "The number of files that failed to process", "format" : "int32", "example" : 2 }, "results" : { "type" : "array", "description" : "Individual results for each file in the batch", "items" : { "$ref" : "#/components/schemas/FileUploadResult" } }, "successCount" : { "type" : "integer", "description" : "The number of successfully processed files", "format" : "int32", "example" : 5 }, "totalCount" : { "type" : "integer", "description" : "The total number of files processed", "format" : "int32", "example" : 7 } }, "description" : "Response from a batch file upload operation" }, "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)" }, "BlockRejectionDetail" : { "type" : "object", "properties" : { "blockId" : { "type" : "string", "description" : "Provider-supplied block identifier", "nullable" : true, "example" : "block-1" }, "code" : { "type" : "string", "description" : "Reject code for the block", "example" : "TRK-4006" }, "firstEpoch" : { "type" : "string", "description" : "ISO-8601 UTC timestamp of the first rejected observation in the block", "nullable" : true, "example" : "2026-04-27T01:14:29.9Z" }, "message" : { "type" : "string", "description" : "Localized rejection message", "example" : "Ambiguous Doppler correction state: YES" } }, "description" : "Per-block rejection detail for a partial file upload result", "nullable" : true }, "BulkMarkOutlierByFileRequest" : { "required" : [ "fileName", "isOutlier" ], "type" : "object", "properties" : { "fileName" : { "maxLength" : 255, "minLength" : 0, "pattern" : "^[a-zA-Z0-9._\\-\\s]+$", "type" : "string", "description" : "Source file name to match against measurements. Matching is exact and case-sensitive.", "example" : "tracking_data_2025-01-15.tdm" }, "isOutlier" : { "type" : "boolean", "description" : "Whether to mark (true) or unmark (false) the measurements as outliers", "example" : true } }, "description" : "Request to bulk mark/unmark measurements as outliers by source file" }, "BulkMarkOutlierRequest" : { "required" : [ "isOutlier", "measurementIds" ], "type" : "object", "properties" : { "isOutlier" : { "type" : "boolean", "description" : "Whether to mark (true) or unmark (false) the measurements as outliers", "example" : true }, "measurementIds" : { "maxItems" : 1000, "minItems" : 1, "type" : "array", "description" : "List of measurement UUIDs to mark or unmark as outliers", "example" : [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ], "items" : { "type" : "string", "description" : "List of measurement UUIDs to mark or unmark as outliers", "format" : "uuid" } } }, "description" : "Request to bulk mark/unmark measurements as outliers by ID list" }, "BulkOutlierResponse" : { "type" : "object", "properties" : { "updatedCount" : { "type" : "integer", "description" : "Number of measurements successfully updated", "format" : "int32", "example" : 42 } }, "description" : "Response for bulk outlier marking operations" }, "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 }, "CreateManeuverInput" : { "required" : [ "attitudeMode", "composition", "name", "spacecraftId" ], "type" : "object", "properties" : { "attitudeMode" : { "type" : "string", "description" : "The attitude mode", "example" : "RSW_ROTATING" }, "composition" : { "type" : "array", "description" : "The burn-segment composition", "items" : { "$ref" : "#/components/schemas/ManeuverCompositionInput" } }, "name" : { "maxLength" : 63, "minLength" : 0, "type" : "string", "description" : "The maneuver name", "example" : "MAN-001" }, "purpose" : { "type" : "string", "description" : "The maneuver purpose", "example" : "[ORBIT]" }, "spacecraftId" : { "type" : "string", "description" : "The VALAR spacecraft ID returned by GET /operations/spacecraft; not a name, NORAD, or COSPAR ID", "example" : "5c58fd70-e08c-47bb-9e84-8c678bd5d1c6" } }, "description" : "The maneuvers to create" }, "CreateManeuverRequest" : { "required" : [ "maneuvers" ], "type" : "object", "properties" : { "maneuvers" : { "type" : "array", "description" : "The maneuvers to create", "items" : { "$ref" : "#/components/schemas/CreateManeuverInput" } } } }, "CreateManeuverResponse" : { "type" : "object", "properties" : { "createdCount" : { "type" : "integer", "description" : "The number of maneuvers created", "format" : "int32", "example" : 1 }, "message" : { "type" : "string", "description" : "A short status message", "example" : "Maneuvers created" } } }, "CreateSpacecraftRequest" : { "required" : [ "absorption", "bodyShape", "dragArea", "dragCoefficient", "launchMass", "name", "reflectivityCoefficient", "specularReflection", "srpArea" ], "type" : "object", "properties" : { "absorption" : { "maximum" : 1.0, "exclusiveMaximum" : false, "minimum" : 0.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.0 }, "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.0 }, "catalogueNoradId" : { "maximum" : 999999, "minimum" : 1, "type" : "integer", "description" : "Selected public catalogue NORAD key; the server derives both identifiers.", "format" : "int32" }, "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.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Operator-typed drag cross-sectional area in m² (DKR-1 §3.6a).", "format" : "double", "example" : 5.0 }, "dragCoefficient" : { "maximum" : 10.0, "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.0 }, "externalKey" : { "maxLength" : 64, "minLength" : 0, "pattern" : "^[A-Za-z0-9._:-]{1,64}$", "type" : "string", "description" : "Caller-assigned external reference key (letters, digits, and. _ : - ; up to 64 chars). Optional; unique within your organization; immutable once set.", "example" : "PARTNER-SAT-001" }, "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.0 }, "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.0 }, "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.0 }, "launchMass" : { "maximum" : 100000, "exclusiveMaximum" : false, "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Total mass at launch in kg", "format" : "double", "example" : 500.0 }, "name" : { "maxLength" : 100, "minLength" : 1, "pattern" : "^[a-zA-Z0-9\\s_-]+$", "type" : "string", "description" : "Name of the spacecraft", "example" : "Sentinel-1A" }, "noradId" : { "maximum" : 999999, "minimum" : 1, "type" : "integer", "description" : "NORAD catalog number", "format" : "int32", "example" : 43013 }, "notYetCatalogued" : { "type" : "boolean", "description" : "Explicitly not yet catalogued. Omit only for legacy API clients or unrelated updates." }, "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.0 }, "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.0, "exclusiveMaximum" : false, "minimum" : 1.0, "exclusiveMinimum" : false, "type" : "number", "description" : "Reflectivity coefficient (1=pure absorber, 2=pure specular reflector)", "format" : "double", "example" : 1.5 }, "specularReflection" : { "maximum" : 1.0, "exclusiveMaximum" : true, "minimum" : 0.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.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Operator-typed solar-radiation-pressure cross-sectional area in m² (DKR-1 §3.6a).", "format" : "double", "example" : 5.0 } }, "description" : "Request payload for creating a new spacecraft" }, "CreateThrusterRequest" : { "required" : [ "direction", "isp", "maxBurnTime", "name", "thrust", "x", "y", "z" ], "type" : "object", "properties" : { "direction" : { "pattern" : "^(X[+-]|Y[+-]|Z[+-])$", "type" : "string", "description" : "Thrust direction in 3D coordinate system", "example" : "Z+", "enum" : [ "X+", "X-", "Y+", "Y-", "Z+", "Z-" ] }, "isp" : { "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Specific impulse in seconds (s). Used to auto-compute type: ISP < 800 = chemical, ISP >= 800 = electric", "format" : "double", "example" : 300.0 }, "maxBurnTime" : { "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Maximum continuous burn duration in seconds (s)", "format" : "double", "example" : 3600.0 }, "name" : { "maxLength" : 100, "minLength" : 0, "type" : "string", "description" : "Thruster name (unique per spacecraft)", "example" : "Main Engine" }, "thrust" : { "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Maximum thrust in Newtons (N)", "format" : "double", "example" : 500.0 }, "x" : { "type" : "number", "description" : "Thruster position X coordinate in meters (m) relative to spacecraft center of mass. Can be negative.", "format" : "double", "example" : 0.0 }, "y" : { "type" : "number", "description" : "Thruster position Y coordinate in meters (m) relative to spacecraft center of mass. Can be negative.", "format" : "double", "example" : 0.0 }, "z" : { "type" : "number", "description" : "Thruster position Z coordinate in meters (m) relative to spacecraft center of mass. Can be negative.", "format" : "double", "example" : -1.5 } }, "description" : "Request to create a new thruster for a spacecraft" }, "DeleteByFileResponse" : { "type" : "object", "properties" : { "deletedCount" : { "type" : "integer", "description" : "Number of measurements permanently deleted", "format" : "int64", "example" : 100 } }, "description" : "Response for bulk deletion of measurements by source file" }, "DerivedNormal" : { "type" : "object", "properties" : { "x" : { "type" : "number", "description" : "Body-frame X component.", "format" : "double", "example" : 1.0 }, "y" : { "type" : "number", "description" : "Body-frame Y component.", "format" : "double", "example" : 0.0 }, "z" : { "type" : "number", "description" : "Body-frame Z component.", "format" : "double", "example" : 0.0 } }, "description" : "A body-frame outward unit-normal triple {x, y, z}." }, "DopplerMetadataDto" : { "type" : "object", "properties" : { "correctionsApplied" : { "type" : "boolean", "description" : "Mirror of the TDM CORRECTIONS_APPLIED metadata — true when all link corrections have already been applied upstream", "nullable" : true, "example" : true }, "ionoState" : { "type" : "string", "description" : "Declared ionospheric correction state (DKR-2 §3.3)", "nullable" : true, "example" : "UNCORRECTED", "enum" : [ "APPLIED", "UNCORRECTED", "ABSENT", "APPLIED", "UNCORRECTED", "ABSENT" ] }, "modality" : { "type" : "string", "description" : "Doppler modality as declared on the originating TDM (DKR-2 §3.2)", "nullable" : true, "example" : "TWO_WAY", "enum" : [ "ONE_WAY", "TWO_WAY", "ONE_WAY", "TWO_WAY" ] }, "receiveBand" : { "type" : "string", "description" : "RF band used for the downlink / receive leg (DKR-2 §3.9). Null when the TDM does not declare a receive band.", "nullable" : true, "example" : "X", "enum" : [ "S", "X", "KA", "S", "X", "KA" ] }, "receiveDelay" : { "minimum" : 0, "type" : "number", "description" : "Receive-leg link delay in seconds (non-negative). Null when the TDM does not declare a value.", "format" : "double", "nullable" : true, "example" : 0.0027 }, "sigmaDefaulted" : { "type" : "boolean", "description" : "True when the ingestion pipeline synthesised the sigma for the parent measurement because the TDM did not declare one", "nullable" : true, "example" : false }, "timetagRef" : { "type" : "string", "description" : "Time-tag reference convention (DKR-2 §3.5). Only RECEIVE is supported in the initial DOPPLER rollout.", "nullable" : true, "example" : "RECEIVE", "enum" : [ "RECEIVE", "RECEIVE" ] }, "transmitBand" : { "type" : "string", "description" : "RF band used for the uplink / transmit leg (DKR-2 §3.9). Null when the TDM does not declare a transmit band (for example ONE_WAY observations).", "nullable" : true, "example" : "S", "enum" : [ "S", "X", "KA", "S", "X", "KA" ] }, "transmitDelay" : { "minimum" : 0, "type" : "number", "description" : "Transmit-leg link delay in seconds (non-negative). Null when the TDM does not declare a value.", "format" : "double", "nullable" : true, "example" : 0.0015 }, "tropoState" : { "type" : "string", "description" : "Declared tropospheric correction state (DKR-2 §3.3)", "nullable" : true, "example" : "APPLIED", "enum" : [ "APPLIED", "UNCORRECTED", "ABSENT", "APPLIED", "UNCORRECTED", "ABSENT" ] }, "turnaroundD" : { "type" : "integer", "description" : "Denominator of the transponder turnaround ratio. Only meaningful for TWO_WAY Doppler with a declared transponder; otherwise null.", "format" : "int32", "nullable" : true, "example" : 221 }, "turnaroundN" : { "type" : "integer", "description" : "Numerator of the transponder turnaround ratio. Only meaningful for TWO_WAY Doppler with a declared transponder; otherwise null.", "format" : "int32", "nullable" : true, "example" : 240 } }, "description" : "Doppler-specific metadata attached to DOPPLER measurements (DKR-2 §2)", "nullable" : true }, "EnvThrusterResponse" : { "type" : "object", "properties" : { "createdAt" : { "type" : "string", "description" : "Timestamp when thruster was created", "format" : "date-time", "example" : "2025-10-22T10:30:00Z" }, "direction" : { "type" : "string", "description" : "Thrust direction in 3D coordinate system", "example" : "Z+", "enum" : [ "X+", "X-", "Y+", "Y-", "Z+", "Z-" ] }, "id" : { "type" : "string", "description" : "Thruster unique identifier (UUID)", "example" : "550e8400-e29b-41d4-a716-446655440000" }, "isp" : { "type" : "number", "description" : "Specific impulse in seconds (s)", "format" : "double", "example" : 300.0 }, "maxBurnTime" : { "type" : "number", "description" : "Maximum continuous burn duration in seconds (s)", "format" : "double", "example" : 3600.0 }, "name" : { "type" : "string", "description" : "Thruster name (unique per spacecraft)", "example" : "Main Engine" }, "spacecraftId" : { "type" : "string", "description" : "Spacecraft ID this thruster belongs to", "example" : "spacecraft-123" }, "thrust" : { "type" : "number", "description" : "Maximum thrust in Newtons (N)", "format" : "double", "example" : 500.0 }, "type" : { "type" : "string", "description" : "Propulsion type (auto-computed from ISP), rendered UPPER_CASE per DT-17", "example" : "CHEMICAL", "enum" : [ "CHEMICAL", "ELECTRIC" ] }, "updatedAt" : { "type" : "string", "description" : "Timestamp when thruster was last updated", "format" : "date-time", "example" : "2025-10-22T15:45:00Z" }, "x" : { "type" : "number", "description" : "Position X coordinate in meters (m)", "format" : "double", "example" : 0.0 }, "y" : { "type" : "number", "description" : "Position Y coordinate in meters (m)", "format" : "double", "example" : 0.0 }, "z" : { "type" : "number", "description" : "Position Z coordinate in meters (m)", "format" : "double", "example" : -1.5 } }, "description" : "Thruster response data" }, "ErrorResponse" : { "type" : "object", "properties" : { "code" : { "type" : "string", "description" : "Stable frontend-dictionary error code", "nullable" : true, "example" : "import.tracking.tdm.parse_failed" }, "correlationId" : { "type" : "string", "description" : "Server-generated opaque identifier for support correlation", "nullable" : true, "example" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "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" : "The HTTP status reason phrase or exception-handler code", "example" : "Bad Request" }, "fieldErrors" : { "type" : "object", "additionalProperties" : { "type" : "string", "description" : "Field-level validation errors (field name to error message)" }, "description" : "Field-level validation errors (field name to error message)" }, "message" : { "type" : "string", "description" : "Detailed error message", "example" : "Invalid spacecraft ID format" }, "params" : { "type" : "object", "additionalProperties" : { "type" : "string", "description" : "Per-key allowlisted structured params for frontend rendering", "nullable" : true }, "description" : "Per-key allowlisted structured params for frontend rendering", "nullable" : true }, "path" : { "type" : "string", "description" : "The request path where the error occurred", "example" : "/api/v1/stm/credentials" }, "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" } }, "description" : "Standard API error response" }, "FileUploadResult" : { "type" : "object", "properties" : { "code" : { "type" : "string", "description" : "Stable frontend-dictionary code for programmatic handling", "nullable" : true, "example" : "import.tracking.tdm.parse_failed" }, "errorCode" : { "type" : "string", "description" : "Deprecated legacy error code. Use 'code' instead.", "nullable" : true, "example" : "TRK-4001", "deprecated" : true }, "errors" : { "type" : "array", "description" : "List of per-block rejection details when status='error' came from a partial ingest (DEV-3104). Null otherwise.", "nullable" : true, "items" : { "$ref" : "#/components/schemas/BlockRejectionDetail" } }, "filename" : { "type" : "string", "description" : "The name of the uploaded file", "example" : "tracking_data_001.tdm" }, "jobId" : { "type" : "string", "description" : "The job ID for tracking async processing status", "nullable" : true, "example" : "550e8400-e29b-41d4-a716-446655440000" }, "measurementContext" : { "$ref" : "#/components/schemas/MeasurementImportContext" }, "message" : { "type" : "string", "description" : "A message describing the result", "example" : "Successfully processed 150 measurements" }, "params" : { "type" : "object", "additionalProperties" : { "type" : "string", "description" : "Per-key allowlisted structured params for frontend rendering", "nullable" : true }, "description" : "Per-key allowlisted structured params for frontend rendering", "nullable" : true }, "status" : { "type" : "string", "description" : "The status of the upload", "example" : "success", "enum" : [ "success", "error", "warning" ] }, "uncertaintySummary" : { "type" : "string", "description" : "Effective OEM assumed uncertainty and source, when the feature is enabled", "nullable" : true } }, "description" : "Result of a single file upload in a batch operation" }, "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.0 }, "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" }, "ImportStateVectorRequest" : { "required" : [ "data", "format" ], "type" : "object", "properties" : { "contentHash" : { "type" : "string", "description" : "Optional SHA-256 content hash from a prior /imports/inspect call. When present, the server re-computes the hash of the uploaded data and rejects with 409 on mismatch. When absent, the check is skipped entirely." }, "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" }, "resolutionFingerprint" : { "type" : "string", "description" : "Optional resolution fingerprint from a prior /imports/inspect call. When present, the server re-computes the fingerprint of the resolved target and rejects with 409 on mismatch. When absent, the check is skipped entirely." }, "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" }, "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 }, "LifecycleUpdateRequest" : { "required" : [ "lifecycleStatus" ], "type" : "object", "properties" : { "confirmTaskDeletion" : { "type" : "boolean", "description" : "Confirms permanent deletion of the craft's scheduled tasks when archiving. Required (true) only to archive a craft that has scheduled tasks; ignored on restore and for a craft with no tasks.", "nullable" : true, "example" : true }, "lifecycleStatus" : { "pattern" : "^(Active|Archived)$", "type" : "string", "description" : "Lifecycle status (ONLY Active or Archived allowed)", "example" : "Archived", "enum" : [ "Active", "Archived" ] } }, "description" : "Request payload for updating spacecraft lifecycle status" }, "ListResponseEnvThrusterResponse" : { "type" : "object", "properties" : { "items" : { "type" : "array", "description" : "The list of items", "items" : { "$ref" : "#/components/schemas/EnvThrusterResponse" } }, "totalCount" : { "type" : "integer", "description" : "Total number of items in the list", "format" : "int32", "example" : 5 } }, "description" : "Wrapper for non-paginated list responses" }, "ListResponseManeuverResponse" : { "type" : "object", "properties" : { "items" : { "type" : "array", "description" : "The list of items", "items" : { "$ref" : "#/components/schemas/ManeuverResponse" } }, "totalCount" : { "type" : "integer", "description" : "Total number of items in the list", "format" : "int32", "example" : 5 } }, "description" : "Wrapper for non-paginated list responses" }, "ListResponsePayloadResponse" : { "type" : "object", "properties" : { "items" : { "type" : "array", "description" : "The list of items", "items" : { "$ref" : "#/components/schemas/PayloadResponse" } }, "totalCount" : { "type" : "integer", "description" : "Total number of items in the list", "format" : "int32", "example" : 5 } }, "description" : "Wrapper for non-paginated list responses" }, "ManeuverCapabilityProfile" : { "type" : "object", "properties" : { "allowedWindows" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverCapabilityWindow" } }, "availableManeuverPowerWatts" : { "type" : "number", "format" : "double" }, "blackoutWindows" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverCapabilityWindow" } }, "minimumManeuverSeparationSeconds" : { "type" : "number", "format" : "double" }, "schemaVersion" : { "type" : "integer", "format" : "int32" }, "thrusters" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverThrusterCapability" } } }, "description" : "Reusable declared maneuver capabilities; null means not configured, not unrestricted." }, "ManeuverCapabilityWindow" : { "type" : "object", "properties" : { "end" : { "type" : "string", "format" : "date-time" }, "start" : { "type" : "string", "format" : "date-time" } } }, "ManeuverComposition" : { "type" : "object", "properties" : { "deltaMass" : { "type" : "number", "format" : "double" }, "deltaV1" : { "type" : "number", "format" : "double" }, "deltaV2" : { "type" : "number", "format" : "double" }, "deltaV3" : { "type" : "number", "format" : "double" }, "duration" : { "type" : "number", "format" : "double" }, "epoch" : { "type" : "string" }, "referenceFrame" : { "type" : "string" } } }, "ManeuverCompositionInput" : { "required" : [ "attitudeMode", "duration", "referenceEpoch", "thrISP", "thrX", "thrY", "thrZ" ], "type" : "object", "properties" : { "accX" : { "type" : "number", "description" : "Read-only acceleration X [m/s^2]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "accY" : { "type" : "number", "description" : "Read-only acceleration Y [m/s^2]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "accZ" : { "type" : "number", "description" : "Read-only acceleration Z [m/s^2]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "attitudeMode" : { "type" : "string", "description" : "Supported local orbital reference frame, such as TNW, RTN, QSW or RSW_ROTATING; unknown and inertial frames are rejected", "example" : "RSW_ROTATING" }, "deltaMass" : { "type" : "number", "description" : "Read-only delta mass [kg]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "duration" : { "type" : "number", "description" : "Duration of the burn segment in seconds", "format" : "double", "example" : 600.0 }, "dvX" : { "type" : "number", "description" : "Read-only delta-V X [m/s]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "dvY" : { "type" : "number", "description" : "Read-only delta-V Y [m/s]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "dvZ" : { "type" : "number", "description" : "Read-only delta-V Z [m/s]; null when unavailable", "format" : "double", "nullable" : true, "readOnly" : true }, "referenceEpoch" : { "type" : "string", "description" : "Reference epoch of the burn segment (ISO-8601)", "format" : "date-time", "example" : "2024-01-01T00:01:40Z" }, "thrISP" : { "maximum" : 10000, "exclusiveMaximum" : false, "minimum" : 50, "exclusiveMinimum" : false, "type" : "number", "description" : "Thrust ISP [s]", "format" : "double" }, "thrX" : { "type" : "number", "description" : "Thrust X axis [N]", "format" : "double" }, "thrY" : { "type" : "number", "description" : "Thrust Y axis [N]", "format" : "double" }, "thrZ" : { "type" : "number", "description" : "Thrust Z axis [N]", "format" : "double" } } }, "ManeuverImportItemResult" : { "type" : "object", "properties" : { "ambiguousTargets" : { "type" : "array", "description" : "Ambiguous target details when errorCode is AMBIGUOUS_SPACECRAFT_MATCH", "nullable" : true, "items" : { "$ref" : "#/components/schemas/AmbiguousTargetDetail" } }, "errorCode" : { "type" : "string", "description" : "The error code if the item failed", "nullable" : true, "example" : "MANEUVER_IMPORT_ERROR" }, "filename" : { "type" : "string", "description" : "The name of the imported item (upload filename)", "example" : "maneuvers.ocm" }, "message" : { "type" : "string", "description" : "A message describing the result", "example" : "Imported successfully" }, "status" : { "type" : "string", "description" : "The status of the item", "example" : "success", "enum" : [ "success", "error" ] } }, "description" : "The individual results for each item in the batch" }, "ManeuverImportResultResponse" : { "type" : "object", "properties" : { "failureCount" : { "type" : "integer", "description" : "The number of items that failed to import", "format" : "int32", "example" : 1 }, "results" : { "type" : "array", "description" : "The individual results for each item in the batch", "items" : { "$ref" : "#/components/schemas/ManeuverImportItemResult" } }, "successCount" : { "type" : "integer", "description" : "The number of successfully imported items", "format" : "int32", "example" : 3 }, "totalCount" : { "type" : "integer", "description" : "The total number of items processed", "format" : "int32", "example" : 4 } } }, "ManeuverOverheadBurn" : { "type" : "object", "properties" : { "anchor" : { "type" : "string", "enum" : [ "BEFORE_MAIN_BURN", "AFTER_MAIN_BURN" ] }, "direction" : { "type" : "string", "enum" : [ "RADIAL_OUT", "RADIAL_IN", "PROGRADE", "RETROGRADE", "NORMAL", "ANTINORMAL" ] }, "durationSeconds" : { "type" : "number", "format" : "double" }, "offsetSeconds" : { "type" : "number", "format" : "double" }, "thrusterId" : { "type" : "string" } } }, "ManeuverResponse" : { "type" : "object", "properties" : { "azimuthDeviation" : { "type" : "number", "format" : "double" }, "conflictingManeuverIds" : { "type" : "array", "items" : { "type" : "string" } }, "creationDate" : { "type" : "string" }, "displayId" : { "type" : "string" }, "elevationDeviation" : { "type" : "number", "format" : "double" }, "epoch" : { "type" : "string" }, "estimatedTotalDeltaV" : { "type" : "number", "format" : "double" }, "maneuverComposition" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverComposition" } }, "maneuverId" : { "type" : "string" }, "name" : { "type" : "string" }, "normPerformance" : { "type" : "number", "format" : "double" }, "performance" : { "type" : "number", "format" : "double" }, "referenceFrame" : { "type" : "string" }, "spacecraftId" : { "type" : "string" }, "totalDeltaMass" : { "type" : "number", "format" : "double" }, "totalDeltaV" : { "type" : "number", "format" : "double" }, "totalDuration" : { "type" : "number", "format" : "double" } }, "description" : "The list of items" }, "ManeuverThrustAlignmentError" : { "type" : "object", "properties" : { "xRadians" : { "type" : "number", "format" : "double" }, "yRadians" : { "type" : "number", "format" : "double" }, "zRadians" : { "type" : "number", "format" : "double" } } }, "ManeuverThrusterCapability" : { "type" : "object", "properties" : { "alignmentError" : { "$ref" : "#/components/schemas/ManeuverThrustAlignmentError" }, "allowedDirections" : { "type" : "array", "items" : { "type" : "string", "enum" : [ "RADIAL_OUT", "RADIAL_IN", "PROGRADE", "RETROGRADE", "NORMAL", "ANTINORMAL" ] } }, "combinedSteeringAllowed" : { "type" : "boolean" }, "dutyCycleWindowSeconds" : { "type" : "number", "format" : "double" }, "eclipsePolicy" : { "type" : "string", "enum" : [ "SUNLIGHT_ONLY", "ECLIPSE_ONLY", "UNRESTRICTED" ] }, "maximumDutyCycle" : { "type" : "number", "format" : "double" }, "minimumBurnSeconds" : { "type" : "number", "format" : "double" }, "minimumImpulseNewtonSeconds" : { "type" : "number", "format" : "double" }, "overheadBurns" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverOverheadBurn" } }, "requiredPowerWatts" : { "type" : "number", "format" : "double" }, "settlingSeconds" : { "type" : "number", "format" : "double" }, "thrusterId" : { "type" : "string" } } }, "MeasurementImportContext" : { "type" : "object", "properties" : { "endDate" : { "type" : "string", "format" : "date-time" }, "measurementTypes" : { "type" : "array", "items" : { "type" : "string" } }, "spacecraftIds" : { "type" : "array", "items" : { "type" : "string" } }, "startDate" : { "type" : "string", "format" : "date-time" } }, "description" : "Spacecraft, types and UTC time span of stored measurements from the uploaded source file", "nullable" : true }, "OemGenerationRequest" : { "required" : [ "finalDate", "initialDate", "referenceFrame", "timeBetweenPoints", "timeSystem" ], "type" : "object", "properties" : { "covarianceFrame" : { "type" : "string", "description" : "Covariance reference frame for OEM covariance matrices", "example" : "RTN", "enum" : [ "RTN", "TNW" ] }, "covarianceFrameValid" : { "type" : "boolean" }, "dateRangeValid" : { "type" : "boolean" }, "finalDate" : { "type" : "string", "description" : "End date for ephemeris generation in ISO-8601 format", "format" : "date-time", "example" : "2024-01-02T00:00:00Z" }, "includeCovariance" : { "type" : "boolean", "description" : "Include covariance matrices in the OEM output", "example" : false, "default" : false }, "initialDate" : { "type" : "string", "description" : "Start date for ephemeris generation in ISO-8601 format", "format" : "date-time", "example" : "2024-01-01T00:00:00Z" }, "referenceFrame" : { "type" : "string", "description" : "Reference frame for position and velocity vectors", "example" : "GCRF", "enum" : [ "GCRF", "EME2000", "ITRF", "TOD", "MOD", "TEME" ] }, "timeBetweenPoints" : { "maximum" : 86400, "minimum" : 60, "type" : "integer", "description" : "Time step between ephemeris points in seconds", "format" : "int32", "example" : 60 }, "timeSpanValid" : { "type" : "boolean" }, "timeSystem" : { "type" : "string", "description" : "Time system for ephemeris timestamps", "example" : "UTC", "enum" : [ "UTC", "TAI", "TT", "TDB", "TCG", "TCB", "GPS" ] } }, "description" : "Request parameters for OEM generation with configurable propagation settings" }, "Pageable" : { "type" : "object", "properties" : { "page" : { "minimum" : 0, "type" : "integer", "format" : "int32" }, "size" : { "minimum" : 1, "type" : "integer", "format" : "int32" }, "sort" : { "type" : "array", "items" : { "type" : "string" } } } }, "PaginatedResponseSpacecraftSummary" : { "type" : "object", "properties" : { "content" : { "type" : "array", "description" : "List of items in the current page", "items" : { "$ref" : "#/components/schemas/SpacecraftSummary" } }, "empty" : { "type" : "boolean", "description" : "Whether the content list is empty", "example" : false }, "first" : { "type" : "boolean", "description" : "Whether this is the first page", "example" : true }, "hasNext" : { "type" : "boolean", "description" : "Whether there are more pages after this one", "example" : true }, "hasPrevious" : { "type" : "boolean", "description" : "Whether there are pages before this one", "example" : false }, "last" : { "type" : "boolean", "description" : "Whether this is the last page", "example" : false }, "page" : { "type" : "integer", "description" : "Current page number (0-indexed)", "format" : "int32", "example" : 0 }, "size" : { "type" : "integer", "description" : "Number of items per page", "format" : "int32", "example" : 20 }, "totalElements" : { "type" : "integer", "description" : "Total number of elements across all pages", "format" : "int64", "example" : 150 }, "totalPages" : { "type" : "integer", "description" : "Total number of pages", "format" : "int32", "example" : 8 } }, "description" : "Paginated response wrapper containing a page of results with navigation metadata" }, "PanelRequest" : { "required" : [ "absorption", "doubleSided", "lengthM", "mountAxisPreset", "mountPositionX", "mountPositionY", "mountPositionZ", "name", "rotationDeg", "specularReflection", "widthM" ], "type" : "object", "properties" : { "absorption" : { "maximum" : 1.0, "exclusiveMaximum" : false, "minimum" : 0.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.0 }, "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.0 }, "mountAxisCustomY" : { "type" : "number", "description" : "Y component of the custom mount-axis direction. See mountAxisCustomX.", "format" : "double", "example" : 0.0 }, "mountAxisCustomZ" : { "type" : "number", "description" : "Z component of the custom mount-axis direction. See mountAxisCustomX.", "format" : "double", "example" : 5.0 }, "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.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.0, "exclusiveMaximum" : true, "minimum" : 0.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.0 }, "specularReflection" : { "maximum" : 1.0, "exclusiveMaximum" : false, "minimum" : 0.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.0 } }, "description" : "One independent solar / radiator panel (DKR-1 §2).", "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.0 }, "mountAxisCustomX" : { "type" : "number", "description" : "X component of the custom mount-axis direction; null unless mountAxisPreset = CUSTOM.", "format" : "double", "example" : 0.0 }, "mountAxisCustomY" : { "type" : "number", "description" : "Y component of the custom mount-axis direction; null unless mountAxisPreset = CUSTOM.", "format" : "double", "example" : 0.0 }, "mountAxisCustomZ" : { "type" : "number", "description" : "Z component of the custom mount-axis direction; null unless mountAxisPreset = CUSTOM.", "format" : "double", "example" : 5.0 }, "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.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.0 }, "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.0 } }, "description" : "One independent solar / radiator panel with its server-derived outward normal (DKR-1 §2 / §3.1)." }, "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-" ] }, "focalLengthMm" : { "type" : "number", "description" : "Optical focal length in millimetres (mm). Optional optical characteristic for downstream modelled-GSD; when present must be positive and finite. Independent of the FOV group — partial optics is tolerated.", "format" : "double", "example" : 120.0 }, "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.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Cone half-angle in degrees (CONICAL only). Range (0°, 90°]; 90° accepted.", "format" : "double", "example" : 30.0 }, "halfHeightDeg" : { "maximum" : 90.0, "exclusiveMaximum" : true, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "FOV half-height in degrees (RECTANGULAR / ELLIPTICAL only). Range (0°, 90°) strict.", "format" : "double", "example" : 20.0 }, "halfWidthDeg" : { "maximum" : 90.0, "exclusiveMaximum" : true, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "FOV half-width in degrees (RECTANGULAR / ELLIPTICAL only). Range (0°, 90°) strict.", "format" : "double", "example" : 10.0 }, "name" : { "maxLength" : 100, "minLength" : 0, "type" : "string", "description" : "Operator-supplied payload name.", "example" : "EO Camera" }, "offNadirAlongTrackDeg" : { "maximum" : 90.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Payload off-nadir along-track slew limit in degrees — how far off-nadir the payload may be pointed along the velocity vector. Optional; range (0°, 90°]. Independent of the FOV group and of the optics fields.", "format" : "double", "example" : 18.0 }, "offNadirCrossTrackDeg" : { "maximum" : 90.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Payload off-nadir cross-track slew limit in degrees — how far off-nadir the payload may be pointed across the velocity vector. Optional; range (0°, 90°]. Independent of the FOV group and of the optics fields.", "format" : "double", "example" : 30.0 }, "pixelPitchUm" : { "type" : "number", "description" : "Detector pixel pitch in micrometres (µm). Optional optical characteristic for downstream modelled-GSD; when present must be positive and finite. Independent of the FOV group — partial optics is tolerated.", "format" : "double", "example" : 5.5 }, "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.0 }, "positionZ" : { "type" : "number", "description" : "Payload mounting position Z in metres (body frame; may be negative).", "format" : "double", "example" : -0.2 }, "radiusDeg" : { "maximum" : 90.0, "exclusiveMaximum" : true, "minimum" : 0.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.0 }, "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 }, "PayloadResponse" : { "type" : "object", "properties" : { "boresight" : { "type" : "string", "enum" : [ "X+", "X-", "Y+", "Y-", "Z+", "Z-" ] }, "focalLengthMm" : { "type" : "number", "format" : "double" }, "fovShape" : { "type" : "string", "enum" : [ "CONICAL", "RECTANGULAR", "ELLIPTICAL", "POLYGON" ] }, "halfAngleDeg" : { "type" : "number", "format" : "double" }, "halfHeightDeg" : { "type" : "number", "format" : "double" }, "halfWidthDeg" : { "type" : "number", "format" : "double" }, "id" : { "type" : "string" }, "name" : { "type" : "string" }, "offNadirAlongTrackDeg" : { "type" : "number", "format" : "double" }, "offNadirCrossTrackDeg" : { "type" : "number", "format" : "double" }, "payloadIndex" : { "type" : "integer", "format" : "int32" }, "pixelPitchUm" : { "type" : "number", "format" : "double" }, "positionX" : { "type" : "number", "format" : "double" }, "positionY" : { "type" : "number", "format" : "double" }, "positionZ" : { "type" : "number", "format" : "double" }, "radiusDeg" : { "type" : "number", "format" : "double" }, "sides" : { "type" : "integer", "format" : "int32" } } }, "PositionStdDevDto" : { "type" : "object", "properties" : { "x" : { "type" : "number", "format" : "double" }, "y" : { "type" : "number", "format" : "double" }, "z" : { "type" : "number", "format" : "double" } } }, "ReferenceResolvingPaginatedResponse" : { "required" : [ "unresolvedSpacecraftReferences" ], "type" : "object", "properties" : { "content" : { "type" : "array", "description" : "List of items in the current page", "items" : { "type" : "object", "description" : "List of items in the current page" } }, "first" : { "type" : "boolean", "description" : "Whether this is the first page", "example" : true }, "hasNext" : { "type" : "boolean", "description" : "Whether there are more pages after this one", "example" : true }, "hasPrevious" : { "type" : "boolean", "description" : "Whether there are pages before this one", "example" : false }, "last" : { "type" : "boolean", "description" : "Whether this is the last page", "example" : false }, "page" : { "type" : "integer", "description" : "Current page number (0-indexed)", "format" : "int32", "example" : 0 }, "size" : { "type" : "integer", "description" : "Number of items per page", "format" : "int32", "example" : 20 }, "totalElements" : { "type" : "integer", "description" : "Total number of elements across all pages", "format" : "int64", "example" : 150 }, "totalPages" : { "type" : "integer", "description" : "Total number of pages", "format" : "int32", "example" : 8 }, "unresolvedSpacecraftReferences" : { "type" : "array", "description" : "Spacecraft references the caller supplied that did not resolve (de-duplicated, caller order preserved). Always present; an empty array means every supplied reference resolved.", "items" : { "type" : "string", "description" : "Spacecraft references the caller supplied that did not resolve (de-duplicated, caller order preserved). Always present; an empty array means every supplied reference resolved." } } }, "description" : "Paginated response wrapper that also reports which supplied spacecraft references did not resolve (drop-report)" }, "ReferenceResolvingPaginatedResponseUnifiedMeasurementDto" : { "required" : [ "unresolvedSpacecraftReferences" ], "type" : "object", "properties" : { "content" : { "type" : "array", "description" : "List of items in the current page", "items" : { "$ref" : "#/components/schemas/UnifiedMeasurementDto" } }, "first" : { "type" : "boolean", "description" : "Whether this is the first page", "example" : true }, "hasNext" : { "type" : "boolean", "description" : "Whether there are more pages after this one", "example" : true }, "hasPrevious" : { "type" : "boolean", "description" : "Whether there are pages before this one", "example" : false }, "last" : { "type" : "boolean", "description" : "Whether this is the last page", "example" : false }, "page" : { "type" : "integer", "description" : "Current page number (0-indexed)", "format" : "int32", "example" : 0 }, "size" : { "type" : "integer", "description" : "Number of items per page", "format" : "int32", "example" : 20 }, "totalElements" : { "type" : "integer", "description" : "Total number of elements across all pages", "format" : "int64", "example" : 150 }, "totalPages" : { "type" : "integer", "description" : "Total number of pages", "format" : "int32", "example" : 8 }, "unresolvedSpacecraftReferences" : { "type" : "array", "description" : "Spacecraft references the caller supplied that did not resolve (de-duplicated, caller order preserved). Always present; an empty array means every supplied reference resolved.", "items" : { "type" : "string", "description" : "Spacecraft references the caller supplied that did not resolve (de-duplicated, caller order preserved). Always present; an empty array means every supplied reference resolved." } } }, "description" : "Paginated response wrapper that also reports which supplied spacecraft references did not resolve (drop-report)" }, "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.0 }, "boxZ" : { "type" : "number", "description" : "Spacecraft box/bus Z dimension (length) in meters", "format" : "double", "example" : 2.0 }, "catalogueNoradId" : { "type" : "integer", "format" : "int32" }, "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.0 }, "dragCoefficient" : { "type" : "number", "description" : "Drag coefficient", "format" : "double", "example" : 2.2 }, "dryMass" : { "type" : "number", "description" : "Mass without propellant in kg", "format" : "double", "example" : 450.0 }, "externalKey" : { "type" : "string", "description" : "Caller-assigned external reference key (unique within your organization; immutable once set). Null when no key has been assigned.", "example" : "PARTNER-SAT-001" }, "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.0 }, "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.0 }, "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.0 }, "launchMass" : { "type" : "number", "description" : "Total mass at launch in kg", "format" : "double", "example" : 500.0 }, "lifecycleStatus" : { "type" : "string", "description" : "Lifecycle status of the spacecraft", "example" : "Active" }, "maneuverCapabilities" : { "$ref" : "#/components/schemas/ManeuverCapabilityProfile" }, "name" : { "type" : "string", "description" : "Name of the spacecraft", "example" : "Sentinel-1A" }, "noradId" : { "type" : "integer", "description" : "NORAD catalog number", "format" : "int32", "example" : 43013 }, "notYetCatalogued" : { "type" : "boolean" }, "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.0 }, "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.0 }, "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.0 }, "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.0 }, "updatedAt" : { "type" : "string", "description" : "Timestamp when the spacecraft was last updated", "format" : "date-time" } }, "description" : "Response containing spacecraft details" }, "SpacecraftSummary" : { "required" : [ "id", "launchMass", "lifecycleStatus", "name" ], "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.0 }, "boxZ" : { "type" : "number", "description" : "Spacecraft box/bus Z dimension (length) in meters", "format" : "double", "example" : 2.0 }, "catalogueNoradId" : { "type" : "integer", "format" : "int32" }, "color" : { "type" : "string", "description" : "Spacecraft color in hex format", "example" : "#FF5733" }, "cosparId" : { "type" : "string", "description" : "COSPAR designation", "example" : "1990-037B" }, "dragArea" : { "type" : "number", "description" : "Operator-typed drag cross-sectional area in m² (null for pre-migration spacecraft)", "format" : "double", "example" : 5.0 }, "dragCoefficient" : { "type" : "number", "description" : "Drag coefficient", "format" : "double", "example" : 2.2 }, "dryMass" : { "type" : "number", "description" : "Dry mass in kilograms", "format" : "double", "example" : 10863.0 }, "externalKey" : { "type" : "string", "description" : "Caller-assigned external reference key (unique within your organization; immutable once set). Null when unassigned.", "example" : "PARTNER-SAT-001" }, "id" : { "type" : "string", "description" : "Unique spacecraft UUID", "example" : "123e4567-e89b-12d3-a456-426614174000" }, "inertiaIxx" : { "type" : "number", "description" : "Principal moment of inertia about the body's primary principal axis (kg·m²). Optional.", "format" : "double", "example" : 1500.0 }, "inertiaIyy" : { "type" : "number", "description" : "Principal moment of inertia about the body's secondary principal axis (kg·m²). Optional.", "format" : "double", "example" : 1700.0 }, "inertiaIzz" : { "type" : "number", "description" : "Principal moment of inertia about the body's tertiary principal axis (kg·m²). Optional.", "format" : "double", "example" : 2100.0 }, "launchMass" : { "type" : "number", "description" : "Launch mass in kilograms", "format" : "double", "example" : 11110.0 }, "lifecycleStatus" : { "type" : "string", "description" : "Lifecycle status (Active or Archived)", "example" : "Active" }, "name" : { "type" : "string", "description" : "Spacecraft name", "example" : "Hubble Space Telescope" }, "noradId" : { "type" : "string", "description" : "NORAD catalog number", "example" : "20580" }, "notYetCatalogued" : { "type" : "boolean" }, "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. 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, computed from edge + sides. Populated only when bodyShape=REGULAR_PRISM; null otherwise.", "format" : "double", "example" : 1.0 }, "prismDiameter" : { "type" : "number", "description" : "Cross-section diameter in the operator's chosen datum, computed from edge + sides. Populated only when bodyShape=REGULAR_PRISM; null otherwise.", "format" : "double", "example" : 0.866025 }, "prismDiameterMeasure" : { "type" : "string", "description" : "Diameter datum the operator used. 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. Populated only when bodyShape=REGULAR_PRISM; null otherwise.", "format" : "double", "example" : 0.5 }, "prismHeightM" : { "type" : "number", "description" : "Regular-prism height L in meters. Populated only when bodyShape=REGULAR_PRISM; null otherwise.", "format" : "double", "example" : 1.0 }, "prismSides" : { "type" : "integer", "description" : "Number of regular-polygon sides N. Populated only when bodyShape=REGULAR_PRISM; null otherwise.", "format" : "int32", "example" : 6 }, "reflectivityCoefficient" : { "type" : "number", "description" : "Reflectivity coefficient", "format" : "double", "example" : 1.0 }, "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.0 } }, "description" : "Simplified spacecraft information for listing" }, "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.0 }, "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.0, 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.0, 3.075, 0.0 ], "items" : { "type" : "number", "description" : "Velocity vector [vx, vy, vz] in km/s", "format" : "double" } }, "warnings" : { "type" : "array", "description" : "Non-fatal validation warnings raised while importing this state vector. Empty when the import raised none. A perigee altitude below OrbitGeometryValidator.PERIGEE_WARN_ALTITUDE_M (120 km) is reported here rather than rejected — the state vector is persisted, but its propagations may be truncated at the 100 km in-flight floor.", "example" : [ ], "items" : { "type" : "string", "description" : "Non-fatal validation warnings raised while importing this state vector. Empty when the import raised none. A perigee altitude below OrbitGeometryValidator.PERIGEE_WARN_ALTITUDE_M (120 km) is reported here rather than rejected — the state vector is persisted, but its propagations may be truncated at the 100 km in-flight floor.", "example" : "[]" } } }, "description" : "State vector representation with position, velocity, and metadata" }, "StoredManeuverResponse" : { "type" : "object", "properties" : { "attitudeMode" : { "type" : "string" }, "composition" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverCompositionInput" } }, "conflictingManeuverIds" : { "type" : "array", "items" : { "type" : "string" } }, "displayId" : { "type" : "string" }, "maneuverId" : { "type" : "string" }, "name" : { "type" : "string" }, "purpose" : { "type" : "string" }, "spacecraftId" : { "type" : "string" } } }, "TargetCandidate" : { "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "Spacecraft canonical id", "example" : "SC-200" }, "identifierType" : { "type" : "string", "description" : "Which identifier type matched", "enum" : [ "NORAD_ID", "COSPAR_ID", "NAME", "INTERNAL_ID", "UNKNOWN" ] }, "identifierValue" : { "type" : "string", "description" : "The identifier value that matched", "example" : "43205" }, "name" : { "type" : "string", "description" : "Spacecraft display name", "nullable" : true } }, "description" : "A candidate spacecraft that matched an identifier" }, "TaskDeletionConflictResponse" : { "type" : "object", "properties" : { "taskCount" : { "type" : "integer", "description" : "Number of scheduled tasks the archive would permanently delete", "format" : "int32", "example" : 3 } }, "description" : "409 body gating an archive-with-tasks on task-deletion confirmation" }, "UnifiedMeasurementDto" : { "type" : "object", "properties" : { "dopplerMetadata" : { "$ref" : "#/components/schemas/DopplerMetadataDto" }, "downlinkFrequency" : { "type" : "number", "description" : "Downlink reference frequency in Hz", "format" : "double", "nullable" : true, "example" : 2200000000 }, "epoch" : { "type" : "string", "description" : "Measurement epoch in ISO-8601 UTC format", "example" : "2025-01-15T12:30:45.123Z" }, "file" : { "type" : "string", "description" : "Original file name from which the measurement was uploaded", "example" : "measurements_2025-01-15.csv" }, "id" : { "type" : "string", "description" : "Unique identifier for this measurement (UUID)", "nullable" : true, "example" : "550e8400-e29b-41d4-a716-446655440000" }, "measurementType" : { "type" : "string", "description" : "Measurement type", "example" : "RADEC", "enum" : [ "RADEC", "AZEL", "RANGE", "PV", "DOPPLER" ] }, "outlier" : { "type" : "boolean", "description" : "Whether this measurement is flagged as an outlier", "example" : false }, "referenceFrame" : { "type" : "string", "description" : "Reference frame for the measurement (ICRF, GCRF, etc.)", "nullable" : true, "example" : "ICRF" }, "sensorId" : { "type" : "string", "description" : "Sensor identifier for ground-based measurements, null for spacecraft-based (PV)", "nullable" : true, "example" : "SENSOR-123" }, "sigmas" : { "type" : "array", "description" : "Measurement uncertainties (1-sigma) per dimension, same length as values", "example" : [ 0.001, 0.001 ], "items" : { "type" : "number", "description" : "Measurement uncertainties (1-sigma) per dimension, same length as values", "format" : "double" } }, "spacecraftId" : { "type" : "string", "description" : "Spacecraft identifier (UUID)", "example" : "550e8400-e29b-41d4-a716-446655440000" }, "values" : { "type" : "array", "description" : "Observed values array. Dimensions depend on measurement type: RADEC[2]={ra, dec} in radians, AZEL[2]={az, el} in radians, RANGE[1]={range} in meters, PV[6]={x, y, z, vx, vy, vz} in meters and m/s", "example" : [ 1.5708, 0.7854 ], "items" : { "type" : "number", "description" : "Observed values array. Dimensions depend on measurement type: RADEC[2]={ra, dec} in radians, AZEL[2]={az, el} in radians, RANGE[1]={range} in meters, PV[6]={x, y, z, vx, vy, vz} in meters and m/s", "format" : "double" } } }, "description" : "Unified measurement data with multi-dimensional values" }, "UpdateManeuverRequest" : { "required" : [ "attitudeMode", "composition", "name" ], "type" : "object", "properties" : { "attitudeMode" : { "type" : "string" }, "composition" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ManeuverCompositionInput" } }, "name" : { "maxLength" : 255, "minLength" : 0, "type" : "string" }, "purpose" : { "type" : "string" } } }, "UpdatePayloadRequest" : { "type" : "object", "properties" : { "boresight" : { "type" : "string", "description" : "New body-frame boresight axis (X+, X-, Y+, Y-, Z+, Z-); omit to leave unchanged.", "example" : "Z+", "enum" : [ "X+", "X-", "Y+", "Y-", "Z+", "Z-" ] }, "focalLengthMm" : { "type" : "number", "description" : "Optical focal length in millimetres (mm) — JsonNullable three-state (DT-8): omit to leave unchanged, send explicit `null` to clear, send a positive finite number to set. Independent of the FOV group.", "format" : "double", "nullable" : true }, "fovShape" : { "type" : "string", "description" : "New FOV shape. Present ⇒ the whole FOV is replaced (set this shape's params, null all others). Absent ⇒ the FOV is left untouched (a lone FOV param is rejected).", "example" : "CONICAL", "enum" : [ "CONICAL", "RECTANGULAR", "ELLIPTICAL", "POLYGON" ] }, "halfAngleDeg" : { "maximum" : 90.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Cone half-angle in degrees (CONICAL only). Range (0°, 90°]; 90° accepted.", "format" : "double", "example" : 30.0 }, "halfHeightDeg" : { "maximum" : 90.0, "exclusiveMaximum" : true, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "FOV half-height in degrees (RECTANGULAR / ELLIPTICAL only). Range (0°, 90°) strict.", "format" : "double", "example" : 20.0 }, "halfWidthDeg" : { "maximum" : 90.0, "exclusiveMaximum" : true, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "FOV half-width in degrees (RECTANGULAR / ELLIPTICAL only). Range (0°, 90°) strict.", "format" : "double", "example" : 10.0 }, "name" : { "maxLength" : 100, "minLength" : 0, "type" : "string", "description" : "New payload name; omit to leave unchanged.", "example" : "EO Camera" }, "offNadirAlongTrackDeg" : { "type" : "number", "description" : "Payload off-nadir along-track slew limit in degrees — JsonNullable three-state (DT-8): omit to leave unchanged, send explicit `null` to clear, send a number in (0°, 90°] to set. Independent of the FOV group and of the optics fields.", "format" : "double", "nullable" : true }, "offNadirCrossTrackDeg" : { "type" : "number", "description" : "Payload off-nadir cross-track slew limit in degrees — JsonNullable three-state (DT-8): omit to leave unchanged, send explicit `null` to clear, send a number in (0°, 90°] to set. Independent of the FOV group and of the optics fields.", "format" : "double", "nullable" : true }, "pixelPitchUm" : { "type" : "number", "description" : "Detector pixel pitch in micrometres (µm) — JsonNullable three-state (DT-8): omit to leave unchanged, send explicit `null` to clear, send a positive finite number to set. Independent of the FOV group.", "format" : "double", "nullable" : true }, "positionX" : { "type" : "number", "description" : "New mounting position X in metres (body frame); omit to leave unchanged.", "format" : "double", "example" : 0.1 }, "positionY" : { "type" : "number", "description" : "New mounting position Y in metres (body frame); omit to leave unchanged.", "format" : "double", "example" : 0.0 }, "positionZ" : { "type" : "number", "description" : "New mounting position Z in metres (body frame); omit to leave unchanged.", "format" : "double", "example" : -0.2 }, "radiusDeg" : { "maximum" : 90.0, "exclusiveMaximum" : true, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Polygon circumscribed (to-vertices) angular radius in degrees (POLYGON only). Range (0°, 90°) strict.", "format" : "double", "example" : 30.0 }, "sides" : { "maximum" : 1000, "minimum" : 3, "type" : "integer", "description" : "Number of polygon sides (POLYGON only). 3 ≤ N ≤ 1000.", "format" : "int32", "example" : 6 } }, "description" : "Partial payload update — every scalar independently optional; the FOV group is an atomic replace (restate fovShape to change any FOV param)." }, "UpdateSpacecraftRequest" : { "type" : "object", "properties" : { "absorption" : { "maximum" : 1.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Optical absorption coefficient α (dimensionless). Range (0.0, 1.0].", "format" : "double", "example" : 0.4 }, "bodyShape" : { "type" : "string", "description" : "Spacecraft body-shape primitive (DKR-2 §2.1). Nullable on update — omit to leave the persisted value unchanged.", "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", "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", "format" : "double", "example" : 1.0 }, "boxZ" : { "maximum" : 1000, "exclusiveMaximum" : false, "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Spacecraft box/bus Z dimension (length) in meters", "format" : "double", "example" : 2.0 }, "catalogueNoradId" : { "maximum" : 999999, "minimum" : 1, "type" : "integer", "description" : "Selected public catalogue NORAD key; the server derives both identifiers.", "format" : "int32" }, "clearColor" : { "type" : "boolean", "description" : "If true, clears the color (sets to null)", "example" : false }, "clearCosparId" : { "type" : "boolean", "description" : "If true, clears the COSPAR ID (sets to null)", "example" : false }, "clearDryMass" : { "type" : "boolean", "description" : "If true, clears the dry mass (sets to null)", "example" : false }, "clearInertiaTensor" : { "type" : "boolean", "description" : "If true, clears the three principal moments (sets to null)", "example" : false }, "clearManeuverCapabilities" : { "type" : "boolean", "description" : "Explicitly remove the maneuver capability declaration. Cannot be combined with a profile." }, "clearNoradId" : { "type" : "boolean", "description" : "If true, clears the NORAD ID (sets to null)", "example" : false }, "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.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Operator-typed drag cross-sectional area in m² (DKR-1 §3.6a).", "format" : "double", "example" : 5.0 }, "dragCoefficient" : { "maximum" : 10.0, "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.0 }, "externalKey" : { "maxLength" : 64, "minLength" : 0, "pattern" : "^[A-Za-z0-9._:-]{1,64}$", "type" : "string", "description" : "Caller-assigned external reference key (letters, digits, and. _ : - ; up to 64 chars). Settable once while unset; immutable once set.", "example" : "PARTNER-SAT-001" }, "inertiaIxx" : { "type" : "number", "description" : "Principal moment of inertia about the body's primary principal axis (kg·m²). Optional.", "format" : "double", "example" : 1500.0 }, "inertiaIyy" : { "type" : "number", "description" : "Principal moment of inertia about the body's secondary principal axis (kg·m²). Optional.", "format" : "double", "example" : 1700.0 }, "inertiaIzz" : { "type" : "number", "description" : "Principal moment of inertia about the body's tertiary principal axis (kg·m²). Optional.", "format" : "double", "example" : 2100.0 }, "launchMass" : { "maximum" : 100000, "exclusiveMaximum" : false, "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Total mass at launch in kg", "format" : "double", "example" : 500.0 }, "maneuverCapabilities" : { "$ref" : "#/components/schemas/ManeuverCapabilityProfile" }, "name" : { "maxLength" : 100, "minLength" : 1, "pattern" : "^[a-zA-Z0-9\\s_-]+$", "type" : "string", "description" : "Name of the spacecraft", "example" : "Sentinel-1A" }, "noradId" : { "maximum" : 999999, "minimum" : 1, "type" : "integer", "description" : "NORAD catalog number", "format" : "int32", "example" : 43013 }, "notYetCatalogued" : { "type" : "boolean", "description" : "Explicitly not yet catalogued. Omit only for legacy API clients or unrelated updates." }, "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. Omit to leave the persisted panels unchanged.", "nullable" : true, "items" : { "$ref" : "#/components/schemas/PanelRequest" } }, "prismAxis" : { "type" : "string", "description" : "Extrusion axis of the regular prism (DKR-1 §3.4). Defaults to Z on create; omit on update to leave unchanged.", "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).", "format" : "double", "example" : 0.866025 }, "prismDiameterMeasure" : { "type" : "string", "description" : "Whether prismDiameter is the inscribed or circumscribed circle diameter (DKR-1 §3.4).", "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).", "format" : "double", "example" : 1.0 }, "prismSides" : { "maximum" : 12, "minimum" : 3, "type" : "integer", "description" : "Number of regular-polygon sides N (DKR-1 §3.4). Range [3, 12].", "format" : "int32", "example" : 6 }, "reflectivityCoefficient" : { "maximum" : 2.0, "exclusiveMaximum" : false, "minimum" : 1.0, "exclusiveMinimum" : false, "type" : "number", "description" : "Reflectivity coefficient (1=pure absorber, 2=pure specular reflector)", "format" : "double", "example" : 1.5 }, "specularReflection" : { "maximum" : 1.0, "exclusiveMaximum" : true, "minimum" : 0.0, "exclusiveMinimum" : false, "type" : "number", "description" : "Optical specular-reflection coefficient ρs (dimensionless). Range [0.0, 1.0). Energy conservation: absorption + specularReflection <= 1.0.", "format" : "double", "example" : 0.3 }, "srpArea" : { "maximum" : 10000.0, "exclusiveMaximum" : false, "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Operator-typed solar-radiation-pressure cross-sectional area in m² (DKR-1 §3.6a).", "format" : "double", "example" : 5.0 }, "updatingBoxDimensions" : { "type" : "boolean" }, "updatingInertiaTensor" : { "type" : "boolean" } }, "description" : "Request payload for partially updating a spacecraft. Only provided fields will be updated." }, "UpdateThrusterRequest" : { "type" : "object", "properties" : { "direction" : { "pattern" : "^(X[+-]|Y[+-]|Z[+-])$", "type" : "string", "description" : "Thrust direction in 3D coordinate system", "example" : "Y+", "enum" : [ "X+", "X-", "Y+", "Y-", "Z+", "Z-" ] }, "isp" : { "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Specific impulse in seconds (s). Changing ISP will re-compute type: ISP < 800 = chemical, ISP >= 800 = electric", "format" : "double", "example" : 350.0 }, "maxBurnTime" : { "minimum" : 0.001, "exclusiveMinimum" : false, "type" : "number", "description" : "Maximum continuous burn duration in seconds (s)", "format" : "double", "example" : 5000.0 }, "name" : { "maxLength" : 100, "minLength" : 0, "type" : "string", "description" : "Thruster name (unique per spacecraft)", "example" : "Updated Main Engine" }, "thrust" : { "minimum" : 0.0, "exclusiveMinimum" : true, "type" : "number", "description" : "Maximum thrust in Newtons (N)", "format" : "double", "example" : 750.0 }, "x" : { "type" : "number", "description" : "Thruster position X coordinate in meters (m) relative to spacecraft center of mass. Can be negative.", "format" : "double", "example" : 1.0 }, "y" : { "type" : "number", "description" : "Thruster position Y coordinate in meters (m) relative to spacecraft center of mass. Can be negative.", "format" : "double", "example" : 2.0 }, "z" : { "type" : "number", "description" : "Thruster position Z coordinate in meters (m) relative to spacecraft center of mass. Can be negative.", "format" : "double", "example" : -2.0 } }, "description" : "Request to update an existing thruster" }, "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" } } }, "x-valar-maneuver-api-version" : "2.0.0" }