{
  "components": {
    "schemas": {
      "AmbiguousTargetDetail": {
        "description": "Detail for an ambiguous target resolution",
        "nullable": true,
        "properties": {
          "candidates": {
            "description": "The candidate spacecraft that matched",
            "items": {
              "$ref": "#/components/schemas/TargetCandidate"
            },
            "type": "array"
          },
          "identifier": {
            "description": "The ambiguous identifier",
            "example": "52771",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CreateManeuverInput": {
        "description": "The maneuvers to create",
        "properties": {
          "attitudeMode": {
            "description": "The attitude mode",
            "example": "RSW_ROTATING",
            "type": "string"
          },
          "composition": {
            "description": "The burn-segment composition",
            "items": {
              "$ref": "#/components/schemas/ManeuverCompositionInput"
            },
            "type": "array"
          },
          "name": {
            "description": "The maneuver name",
            "example": "MAN-001",
            "maxLength": 63,
            "minLength": 0,
            "type": "string"
          },
          "purpose": {
            "description": "The maneuver purpose",
            "example": "[ORBIT]",
            "type": "string"
          },
          "spacecraftId": {
            "description": "The VALAR spacecraft ID returned by GET /operations/spacecraft; not a name, NORAD, or COSPAR ID",
            "example": "5c58fd70-e08c-47bb-9e84-8c678bd5d1c6",
            "type": "string"
          }
        },
        "required": [
          "attitudeMode",
          "composition",
          "name",
          "spacecraftId"
        ],
        "type": "object"
      },
      "CreateManeuverRequest": {
        "properties": {
          "maneuvers": {
            "description": "The maneuvers to create",
            "items": {
              "$ref": "#/components/schemas/CreateManeuverInput"
            },
            "type": "array"
          }
        },
        "required": [
          "maneuvers"
        ],
        "type": "object"
      },
      "CreateManeuverResponse": {
        "properties": {
          "createdCount": {
            "description": "The number of maneuvers created",
            "example": 1,
            "format": "int32",
            "type": "integer"
          },
          "message": {
            "description": "A short status message",
            "example": "Maneuvers created",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ErrorResponse": {
        "description": "Standard API error response",
        "properties": {
          "code": {
            "description": "Stable frontend-dictionary error code",
            "example": "import.tracking.tdm.parse_failed",
            "nullable": true,
            "type": "string"
          },
          "correlationId": {
            "description": "Server-generated opaque identifier for support correlation",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "nullable": true,
            "type": "string"
          },
          "details": {
            "additionalProperties": {
              "description": "Structured error details with scenario-specific context fields",
              "nullable": true,
              "type": "object"
            },
            "description": "Structured error details with scenario-specific context fields",
            "nullable": true,
            "type": "object"
          },
          "error": {
            "description": "The HTTP status reason phrase or exception-handler code",
            "example": "Bad Request",
            "type": "string"
          },
          "fieldErrors": {
            "additionalProperties": {
              "description": "Field-level validation errors (field name to error message)",
              "type": "string"
            },
            "description": "Field-level validation errors (field name to error message)",
            "type": "object"
          },
          "message": {
            "description": "Detailed error message",
            "example": "Invalid spacecraft ID format",
            "type": "string"
          },
          "params": {
            "additionalProperties": {
              "description": "Per-key allowlisted structured params for frontend rendering",
              "nullable": true,
              "type": "string"
            },
            "description": "Per-key allowlisted structured params for frontend rendering",
            "nullable": true,
            "type": "object"
          },
          "path": {
            "description": "The request path where the error occurred",
            "example": "/api/v1/stm/credentials",
            "type": "string"
          },
          "status": {
            "description": "The HTTP status code",
            "example": 400,
            "format": "int32",
            "type": "integer"
          },
          "timestamp": {
            "description": "The timestamp when the error occurred",
            "example": "2025-11-14T10:15:30.123Z",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ListResponseManeuverResponse": {
        "description": "Wrapper for non-paginated list responses",
        "properties": {
          "items": {
            "description": "The list of items",
            "items": {
              "$ref": "#/components/schemas/ManeuverResponse"
            },
            "type": "array"
          },
          "totalCount": {
            "description": "Total number of items in the list",
            "example": 5,
            "format": "int32",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ManeuverComposition": {
        "properties": {
          "deltaMass": {
            "format": "double",
            "type": "number"
          },
          "deltaV1": {
            "format": "double",
            "type": "number"
          },
          "deltaV2": {
            "format": "double",
            "type": "number"
          },
          "deltaV3": {
            "format": "double",
            "type": "number"
          },
          "duration": {
            "format": "double",
            "type": "number"
          },
          "epoch": {
            "type": "string"
          },
          "referenceFrame": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ManeuverCompositionInput": {
        "properties": {
          "accX": {
            "description": "Read-only acceleration X [m/s^2]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "accY": {
            "description": "Read-only acceleration Y [m/s^2]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "accZ": {
            "description": "Read-only acceleration Z [m/s^2]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "attitudeMode": {
            "description": "Supported local orbital reference frame, such as TNW, RTN, QSW or RSW_ROTATING; unknown and inertial frames are rejected",
            "example": "RSW_ROTATING",
            "type": "string"
          },
          "deltaMass": {
            "description": "Read-only delta mass [kg]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "duration": {
            "description": "Duration of the burn segment in seconds",
            "example": 600.0,
            "format": "double",
            "type": "number"
          },
          "dvX": {
            "description": "Read-only delta-V X [m/s]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "dvY": {
            "description": "Read-only delta-V Y [m/s]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "dvZ": {
            "description": "Read-only delta-V Z [m/s]; null when unavailable",
            "format": "double",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "referenceEpoch": {
            "description": "Reference epoch of the burn segment (ISO-8601)",
            "example": "2024-01-01T00:01:40Z",
            "format": "date-time",
            "type": "string"
          },
          "thrISP": {
            "description": "Thrust ISP [s]",
            "exclusiveMaximum": false,
            "exclusiveMinimum": false,
            "format": "double",
            "maximum": 10000,
            "minimum": 50,
            "type": "number"
          },
          "thrX": {
            "description": "Thrust X axis [N]",
            "format": "double",
            "type": "number"
          },
          "thrY": {
            "description": "Thrust Y axis [N]",
            "format": "double",
            "type": "number"
          },
          "thrZ": {
            "description": "Thrust Z axis [N]",
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "attitudeMode",
          "duration",
          "referenceEpoch",
          "thrISP",
          "thrX",
          "thrY",
          "thrZ"
        ],
        "type": "object"
      },
      "ManeuverImportItemResult": {
        "description": "The individual results for each item in the batch",
        "properties": {
          "ambiguousTargets": {
            "description": "Ambiguous target details when errorCode is AMBIGUOUS_SPACECRAFT_MATCH",
            "items": {
              "$ref": "#/components/schemas/AmbiguousTargetDetail"
            },
            "nullable": true,
            "type": "array"
          },
          "errorCode": {
            "description": "The error code if the item failed",
            "example": "MANEUVER_IMPORT_ERROR",
            "nullable": true,
            "type": "string"
          },
          "filename": {
            "description": "The name of the imported item (upload filename)",
            "example": "maneuvers.ocm",
            "type": "string"
          },
          "message": {
            "description": "A message describing the result",
            "example": "Imported successfully",
            "type": "string"
          },
          "status": {
            "description": "The status of the item",
            "enum": [
              "success",
              "error"
            ],
            "example": "success",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ManeuverImportResultResponse": {
        "properties": {
          "failureCount": {
            "description": "The number of items that failed to import",
            "example": 1,
            "format": "int32",
            "type": "integer"
          },
          "results": {
            "description": "The individual results for each item in the batch",
            "items": {
              "$ref": "#/components/schemas/ManeuverImportItemResult"
            },
            "type": "array"
          },
          "successCount": {
            "description": "The number of successfully imported items",
            "example": 3,
            "format": "int32",
            "type": "integer"
          },
          "totalCount": {
            "description": "The total number of items processed",
            "example": 4,
            "format": "int32",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ManeuverResponse": {
        "description": "The list of items",
        "properties": {
          "azimuthDeviation": {
            "format": "double",
            "type": "number"
          },
          "conflictingManeuverIds": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "creationDate": {
            "type": "string"
          },
          "displayId": {
            "type": "string"
          },
          "elevationDeviation": {
            "format": "double",
            "type": "number"
          },
          "epoch": {
            "type": "string"
          },
          "estimatedTotalDeltaV": {
            "format": "double",
            "type": "number"
          },
          "maneuverComposition": {
            "items": {
              "$ref": "#/components/schemas/ManeuverComposition"
            },
            "type": "array"
          },
          "maneuverId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "normPerformance": {
            "format": "double",
            "type": "number"
          },
          "performance": {
            "format": "double",
            "type": "number"
          },
          "referenceFrame": {
            "type": "string"
          },
          "spacecraftId": {
            "type": "string"
          },
          "totalDeltaMass": {
            "format": "double",
            "type": "number"
          },
          "totalDeltaV": {
            "format": "double",
            "type": "number"
          },
          "totalDuration": {
            "format": "double",
            "type": "number"
          }
        },
        "type": "object"
      },
      "StoredManeuverResponse": {
        "properties": {
          "attitudeMode": {
            "type": "string"
          },
          "composition": {
            "items": {
              "$ref": "#/components/schemas/ManeuverCompositionInput"
            },
            "type": "array"
          },
          "conflictingManeuverIds": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "displayId": {
            "type": "string"
          },
          "maneuverId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "spacecraftId": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TargetCandidate": {
        "description": "A candidate spacecraft that matched an identifier",
        "properties": {
          "id": {
            "description": "Spacecraft canonical id",
            "example": "SC-200",
            "type": "string"
          },
          "identifierType": {
            "description": "Which identifier type matched",
            "enum": [
              "NORAD_ID",
              "COSPAR_ID",
              "NAME",
              "INTERNAL_ID",
              "UNKNOWN"
            ],
            "type": "string"
          },
          "identifierValue": {
            "description": "The identifier value that matched",
            "example": "43205",
            "type": "string"
          },
          "name": {
            "description": "Spacecraft display name",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateManeuverRequest": {
        "properties": {
          "attitudeMode": {
            "type": "string"
          },
          "composition": {
            "items": {
              "$ref": "#/components/schemas/ManeuverCompositionInput"
            },
            "type": "array"
          },
          "name": {
            "maxLength": 255,
            "minLength": 0,
            "type": "string"
          },
          "purpose": {
            "type": "string"
          }
        },
        "required": [
          "attitudeMode",
          "composition",
          "name"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "description": "API Key (format: vsp_sk_...)",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Create, read, update, delete, import, and export spacecraft maneuvers. Integration guide: https://docs.valar.space/api-reference/maneuvers",
    "title": "VALAR Maneuver API",
    "version": "2.0.0"
  },
  "openapi": "3.0.1",
  "paths": {
    "/operations/maneuvers": {
      "get": {
        "operationId": "getOperationsManeuvers",
        "parameters": [
          {
            "in": "query",
            "name": "spacecraftIds",
            "required": true,
            "schema": {
              "items": {
                "type": "string"
              },
              "maxItems": 50,
              "minItems": 1,
              "type": "array"
            }
          },
          {
            "in": "query",
            "name": "startDate",
            "required": true,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "endDate",
            "required": true,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "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\u2013100 maneuverIds, without time bounds; or select a range using 1\u201350 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": {
              "items": {
                "type": "string"
              },
              "maxItems": 50,
              "minItems": 1,
              "type": "array"
            }
          },
          {
            "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": {
              "items": {
                "maxLength": 63,
                "type": "string"
              },
              "maxItems": 100,
              "minItems": 1,
              "type": "array",
              "uniqueItems": true
            },
            "style": "form"
          },
          {
            "in": "query",
            "name": "startDate",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "endDate",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/zip": {
                "schema": {
                  "format": "byte",
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "format": "byte",
                  "type": "string"
                }
              }
            },
            "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": {
                "properties": {
                  "files": {
                    "items": {
                      "format": "binary",
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "files"
                ],
                "type": "object"
              }
            }
          }
        },
        "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"
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://api.valar.space"
    }
  ],
  "tags": [
    {
      "name": "Maneuvers"
    }
  ]
}