> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valar.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Partially update an OPS-scoped spacecraft

> Updates only the provided fields of a spacecraft resolved strictly by id within the OPERATIONS environment. Returns 404 if the id lives in a different environment (D-8 env-explicit lookup).



## OpenAPI

````yaml https://api.valar.space/api-docs/mintlify patch /operations/spacecraft/{id}
openapi: 3.0.1
info:
  contact:
    email: api@valar.space
    name: Valar Space
    url: https://valar.space
  description: >-
    <H4>Welcome to the documentation for the Valar Operations API, here are some
    quick tips if you just landed!</H4><ol><li> The top level elements are the
    <b>Resources</b> accessible via the API and the different queries used to
    interact with each resource via the appropriate HTTP method call.</li><li>
    You can expand each method to get further information on the expected input
    parameters and the different responses that can be received.</li><li>For
    both the input parameters and responses, an <b>Example</b> is present for
    clarification.</li><li>For further details, the example snipped can be
    switched to <b>Schema</b> view, where a detailed explanation of each element
    can be found.</li><li>The <b>Try it out</b> 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.</li><li><b>Before starting</b>, remember
    to use the token endpoint and activate the token with the <b>Authorize</b>
    button.</li></ol>
  title: API Documentation
  version: 1.0.0
servers:
  - url: /
    description: Default Server URL
  - url: https://api.valar.space
    description: API Server
security:
  - apiKeyAuth: []
tags:
  - description: >-
      Env-scoped thruster CRUD for the MISSION_ANALYSIS environment
      (EnvironmentFilter activates server-side via the /mission-analysis/ URL
      prefix).
    name: Mission Analysis Thrusters
  - description: >-
      Operations for managing state vectors — listing, importing, exporting, and
      deleting spacecraft state data
    name: State Vectors
  - description: >-
      Env-scoped spacecraft writes for the OPERATIONS environment
      (EnvironmentFilter activates server-side via the /operations/ URL prefix).
    name: Operations Spacecraft (write)
  - description: >-
      Env-scoped per-item payload (sensor) CRUD for the MISSION_ANALYSIS
      environment (EnvironmentFilter activates server-side via the
      /mission-analysis/ URL prefix).
    name: Mission Analysis Payloads
  - description: >-
      Env-scoped thruster CRUD for the OPERATIONS environment (EnvironmentFilter
      activates server-side via the /operations/ URL prefix).
    name: Operations Thrusters
  - description: >-
      Env-scoped spacecraft reads for the MISSION_ANALYSIS environment
      (EnvironmentFilter activates server-side via the /mission-analysis/ URL
      prefix).
    name: Mission Analysis Spacecraft
  - description: >-
      Env-scoped spacecraft reads for the OPERATIONS environment
      (EnvironmentFilter activates server-side via the /operations/ URL prefix).
    name: Operations Spacecraft
  - description: >-
      Env-scoped per-item payload (sensor) CRUD for the OPERATIONS environment
      (EnvironmentFilter activates server-side via the /operations/ URL prefix).
    name: Operations Payloads
  - description: >-
      Env-scoped spacecraft writes for the MISSION_ANALYSIS environment
      (EnvironmentFilter activates server-side via the /mission-analysis/ URL
      prefix).
    name: Mission Analysis Spacecraft (write)
paths:
  /operations/spacecraft/{id}:
    patch:
      tags:
        - Operations Spacecraft (write)
      summary: Partially update an OPS-scoped spacecraft
      description: >-
        Updates only the provided fields of a spacecraft resolved strictly by id
        within the OPERATIONS environment. Returns 404 if the id lives in a
        different environment (D-8 env-explicit lookup).
      operationId: partialUpdateOperationsSpacecraft
      parameters:
        - description: Spacecraft identifier (UUID)
          example: 12345
          in: path
          name: id
          required: true
          schema:
            type: string
      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 OPS env access or PERM_write:spacecraft
            permission
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Spacecraft not found in OPS scope
      security:
        - bearerAuth: []
components:
  schemas:
    UpdateSpacecraftRequest:
      type: object
      properties:
        absorption:
          maximum: 1
          exclusiveMaximum: false
          minimum: 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
        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
        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
        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
          exclusiveMaximum: false
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: Operator-typed drag cross-sectional area in m² (DKR-1 §3.6a).
          format: double
          example: 5
        dragCoefficient:
          maximum: 10
          exclusiveMaximum: false
          minimum: 0.1
          exclusiveMinimum: false
          type: number
          description: 'Drag coefficient (typical values: 1.0-3.0)'
          format: double
          example: 2.2
        dryMass:
          maximum: 100000
          exclusiveMaximum: false
          minimum: 0.001
          exclusiveMinimum: false
          type: number
          description: Mass without propellant in kg
          format: double
          example: 450
        inertiaIxx:
          type: number
          description: >-
            Principal moment of inertia about the body's primary principal axis
            (kg·m²). Optional.
          format: double
          example: 1500
        inertiaIyy:
          type: number
          description: >-
            Principal moment of inertia about the body's secondary principal
            axis (kg·m²). Optional.
          format: double
          example: 1700
        inertiaIzz:
          type: number
          description: >-
            Principal moment of inertia about the body's tertiary principal axis
            (kg·m²). Optional.
          format: double
          example: 2100
        launchMass:
          maximum: 100000
          exclusiveMaximum: false
          minimum: 0.001
          exclusiveMinimum: false
          type: number
          description: Total mass at launch in kg
          format: double
          example: 500
        name:
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9\s_-]+$
          type: string
          description: Name of the spacecraft
          example: Sentinel-1A
        noradId:
          maximum: 99999
          minimum: 1
          type: integer
          description: NORAD catalog number
          format: int32
          example: 43013
        panels:
          maxItems: 8
          minItems: 0
          type: array
          description: >-
            Advanced-geometry solar panels attached to this spacecraft. 0..8
            entries; per-panel validation cascades via @Valid. 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
        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
          exclusiveMaximum: false
          minimum: 1
          exclusiveMinimum: false
          type: number
          description: >-
            Reflectivity coefficient (1=pure absorber, 2=pure specular
            reflector)
          format: double
          example: 1.5
        specularReflection:
          maximum: 1
          exclusiveMaximum: true
          minimum: 0
          exclusiveMinimum: false
          type: number
          description: >-
            Optical specular-reflection coefficient ρs (dimensionless). Range
            [0.0, 1.0). Energy conservation: absorption + specularReflection <=
            1.0.
          format: double
          example: 0.3
        srpArea:
          maximum: 10000
          exclusiveMaximum: false
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: >-
            Operator-typed solar-radiation-pressure cross-sectional area in m²
            (DKR-1 §3.6a).
          format: double
          example: 5
        updatingBoxDimensions:
          type: boolean
        updatingInertiaTensor:
          type: boolean
      description: >-
        Request payload for partially updating a spacecraft. Only provided
        fields will be updated.
    SpacecraftResponse:
      type: object
      properties:
        absorption:
          type: number
          description: Optical absorption coefficient α (dimensionless). Range (0.0, 1.0].
          format: double
          example: 0.4
        bodyShape:
          type: string
          description: Body geometry primitive (BOX or REGULAR_PRISM).
          example: BOX
          enum:
            - BOX
            - REGULAR_PRISM
        boxX:
          type: number
          description: Spacecraft box/bus X dimension (width) in meters
          format: double
          example: 1.5
        boxY:
          type: number
          description: Spacecraft box/bus Y dimension (height) in meters
          format: double
          example: 1
        boxZ:
          type: number
          description: Spacecraft box/bus Z dimension (length) in meters
          format: double
          example: 2
        color:
          type: string
          description: Spacecraft color in hex format
          example: '#FF5733'
        cosparId:
          type: string
          description: COSPAR international designator
          example: 2024-001A
        createdAt:
          type: string
          description: Timestamp when the spacecraft was created
          format: date-time
        dragArea:
          type: number
          description: >-
            Operator-typed drag cross-sectional area in m² (null for
            pre-migration spacecraft)
          format: double
          example: 5
        dragCoefficient:
          type: number
          description: Drag coefficient
          format: double
          example: 2.2
        dryMass:
          type: number
          description: Mass without propellant in kg
          format: double
          example: 450
        environment:
          type: string
          description: >-
            Environment scope of this spacecraft (OPERATIONS or
            MISSION_ANALYSIS).
          example: MISSION_ANALYSIS
        id:
          type: string
          description: Unique identifier of the spacecraft
          example: 550e8400-e29b-41d4-a716-446655440000
        inertiaIxx:
          type: number
          description: >-
            Principal moment of inertia about the body's primary principal axis
            (kg·m²). Optional; null when inertia is not configured.
          format: double
          example: 1500
        inertiaIyy:
          type: number
          description: >-
            Principal moment of inertia about the body's secondary principal
            axis (kg·m²). Optional; null when inertia is not configured.
          format: double
          example: 1700
        inertiaIzz:
          type: number
          description: >-
            Principal moment of inertia about the body's tertiary principal axis
            (kg·m²). Optional; null when inertia is not configured.
          format: double
          example: 2100
        launchMass:
          type: number
          description: Total mass at launch in kg
          format: double
          example: 500
        lifecycleStatus:
          type: string
          description: Lifecycle status of the spacecraft
          example: Active
        name:
          type: string
          description: Name of the spacecraft
          example: Sentinel-1A
        noradId:
          type: integer
          description: NORAD catalog number
          format: int32
          example: 43013
        organizationId:
          type: string
          description: Organization ID that owns this spacecraft
          example: VALAR
        panels:
          type: array
          description: >-
            Per-panel rows (0..8). Each entry carries dimensions, attachment
            face, and orientation angles.
          items:
            $ref: '#/components/schemas/PanelResponse'
        prismAxis:
          type: string
          description: >-
            Extrusion axis of the regular prism (DKR-1 §3.4). Populated only
            when bodyShape=REGULAR_PRISM; null otherwise.
          example: Z
          enum:
            - X
            - 'Y'
            - Z
        prismComplementaryDiameter:
          type: number
          description: >-
            Cross-section diameter in the OTHER datum (the complement of
            prismDiameterMeasure), computed from edge + sides (DKR-1 §3.4).
            Populated only when bodyShape=REGULAR_PRISM; null otherwise.
          format: double
          example: 1
        prismDiameter:
          type: number
          description: >-
            Cross-section diameter in the operator's chosen datum
            (prismDiameterMeasure), computed from edge + sides (DKR-1 §3.4).
            Populated only when bodyShape=REGULAR_PRISM; null otherwise.
          format: double
          example: 0.866025
        prismDiameterMeasure:
          type: string
          description: >-
            Which diameter datum the operator used to size the cross-section
            (DKR-1 §3.4). Populated only when bodyShape=REGULAR_PRISM; null
            otherwise.
          example: INSCRIBED
          enum:
            - INSCRIBED
            - CIRCUMSCRIBED
        prismEdgeM:
          type: number
          description: >-
            Canonical regular-polygon edge length a in meters (DKR-1 §6) — the
            persisted source-of-truth cross-section dimension. Populated only
            when bodyShape=REGULAR_PRISM; null otherwise.
          format: double
          example: 0.5
        prismHeightM:
          type: number
          description: >-
            Regular-prism height L along the extrusion axis in meters. Populated
            only when bodyShape=REGULAR_PRISM; null otherwise.
          format: double
          example: 1
        prismSides:
          type: integer
          description: >-
            Number of regular-polygon sides N (DKR-1 §3.4). Populated only when
            bodyShape=REGULAR_PRISM; null otherwise.
          format: int32
          example: 6
        reflectivityCoefficient:
          type: number
          description: Reflectivity coefficient
          format: double
          example: 1
        specularReflection:
          type: number
          description: >-
            Optical specular-reflection coefficient ρs (dimensionless). Range
            [0.0, 1.0).
          format: double
          example: 0.3
        srpArea:
          type: number
          description: >-
            Operator-typed SRP cross-sectional area in m² (null for
            pre-migration spacecraft)
          format: double
          example: 5
        updatedAt:
          type: string
          description: Timestamp when the spacecraft was last updated
          format: date-time
      description: Response containing spacecraft details
    ErrorResponse:
      type: object
      properties:
        details:
          type: object
          additionalProperties:
            type: object
            description: Structured error details with scenario-specific context fields
            nullable: true
          description: Structured error details with scenario-specific context fields
          nullable: true
        error:
          type: string
          description: HTTP status reason phrase or error category
          example: Bad Request
        fieldErrors:
          type: object
          additionalProperties:
            type: string
            description: >-
              Per-field validation error messages, present only for validation
              errors
            nullable: true
          description: >-
            Per-field validation error messages, present only for validation
            errors
          nullable: true
        message:
          type: string
          description: Detailed error message
          example: Validation failed
        path:
          type: string
          description: The request path where the error occurred
          example: /measurements
        status:
          type: integer
          description: The HTTP status code
          format: int32
          example: 400
        timestamp:
          type: string
          description: The timestamp when the error occurred
          format: date-time
          example: '2025-11-14T10:15:30.123Z'
    BearerTokenErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: OAuth 2.0 error code
          example: invalid_token
        error_description:
          type: string
          description: Human-readable error description
          example: An error occurred while attempting to decode the Jwt
      description: OAuth 2.0 Bearer Token error response (RFC 6750)
    PanelRequest:
      required:
        - absorption
        - doubleSided
        - lengthM
        - mountAxisPreset
        - mountPositionX
        - mountPositionY
        - mountPositionZ
        - name
        - rotationDeg
        - specularReflection
        - widthM
      type: object
      properties:
        absorption:
          maximum: 1
          exclusiveMaximum: false
          minimum: 0
          exclusiveMinimum: false
          type: number
          description: >-
            Per-panel optical absorption coefficient α (dimensionless). Range
            [0.0, 1.0]. Energy conservation: absorption + specularReflection ≤
            1.0.
          format: double
          example: 0.3
        doubleSided:
          type: boolean
          description: >-
            Whether the panel contributes drag / SRP area on both faces (DKR-1
            §3.1). Required.
          example: true
        lengthM:
          minimum: 0.001
          exclusiveMinimum: false
          type: number
          description: Plate length (along the panel's local L axis) in meters. Required.
          format: double
          example: 2
        mountAxisCustomX:
          type: number
          description: >-
            X component of the custom mount-axis direction. Required and
            non-zero in magnitude only when mountAxisPreset = CUSTOM; ignored
            otherwise.
          format: double
          example: 0
        mountAxisCustomY:
          type: number
          description: >-
            Y component of the custom mount-axis direction. See
            mountAxisCustomX.
          format: double
          example: 0
        mountAxisCustomZ:
          type: number
          description: >-
            Z component of the custom mount-axis direction. See
            mountAxisCustomX.
          format: double
          example: 5
        mountAxisPreset:
          type: string
          description: >-
            Body-frame mount axis the panel is oriented along. One of the six
            cardinal presets (PLUS_X/MINUS_X/PLUS_Y/MINUS_Y/PLUS_Z/MINUS_Z) or
            CUSTOM (then mountAxisCustomX/Y/Z carry the direction).
          example: PLUS_Z
          enum:
            - PLUS_X
            - MINUS_X
            - PLUS_Y
            - MINUS_Y
            - PLUS_Z
            - MINUS_Z
            - CUSTOM
        mountPositionX:
          type: number
          description: >-
            Mount-point X coordinate in the spacecraft body frame (meters).
            Required; may be negative; no cap.
          format: double
          example: -1.5
        mountPositionY:
          type: number
          description: >-
            Mount-point Y coordinate in the spacecraft body frame (meters).
            Required; may be negative; no cap.
          format: double
          example: 0
        mountPositionZ:
          type: number
          description: >-
            Mount-point Z coordinate in the spacecraft body frame (meters).
            Required; may be negative; no cap.
          format: double
          example: 0.25
        name:
          maxLength: 100
          minLength: 0
          type: string
          description: >-
            Operator-facing panel name. Required, non-blank, ≤ 100 chars; unique
            per spacecraft (case-insensitive).
          example: Port array
        rotationDeg:
          maximum: 360
          exclusiveMaximum: true
          minimum: 0
          exclusiveMinimum: false
          type: number
          description: >-
            Rotation about the mount axis (degrees). Range [0°, 360°) half-open
            — values at 360° are equivalent to 0° and are rejected so the wire
            contract stays canonical.
          format: double
          example: 90
        specularReflection:
          maximum: 1
          exclusiveMaximum: false
          minimum: 0
          exclusiveMinimum: false
          type: number
          description: >-
            Per-panel optical specular-reflection coefficient ρs
            (dimensionless). Range [0.0, 1.0]. Energy conservation: absorption +
            specularReflection ≤ 1.0.
          format: double
          example: 0.2
        widthM:
          minimum: 0.001
          exclusiveMinimum: false
          type: number
          description: Plate width (along the panel's local W axis) in meters. Required.
          format: double
          example: 1
      description: One independent solar / radiator panel (DKR-1 §2).
      nullable: true
    PanelResponse:
      type: object
      properties:
        absorption:
          type: number
          description: Per-panel optical absorption coefficient α (dimensionless).
          format: double
          example: 0.3
        derivedNormal:
          $ref: '#/components/schemas/DerivedNormal'
        doubleSided:
          type: boolean
          description: Whether the panel contributes drag / SRP area on both faces.
          example: true
        lengthM:
          type: number
          description: Plate length (along the panel's local L axis) in meters.
          format: double
          example: 2
        mountAxisCustomX:
          type: number
          description: >-
            X component of the custom mount-axis direction; null unless
            mountAxisPreset = CUSTOM.
          format: double
          example: 0
        mountAxisCustomY:
          type: number
          description: >-
            Y component of the custom mount-axis direction; null unless
            mountAxisPreset = CUSTOM.
          format: double
          example: 0
        mountAxisCustomZ:
          type: number
          description: >-
            Z component of the custom mount-axis direction; null unless
            mountAxisPreset = CUSTOM.
          format: double
          example: 5
        mountAxisPreset:
          type: string
          description: Body-frame mount axis the panel is oriented along.
          example: PLUS_Z
          enum:
            - PLUS_X
            - MINUS_X
            - PLUS_Y
            - MINUS_Y
            - PLUS_Z
            - MINUS_Z
            - CUSTOM
        mountPositionX:
          type: number
          description: Mount-point X coordinate in the spacecraft body frame (meters).
          format: double
          example: -1.5
        mountPositionY:
          type: number
          description: Mount-point Y coordinate in the spacecraft body frame (meters).
          format: double
          example: 0
        mountPositionZ:
          type: number
          description: Mount-point Z coordinate in the spacecraft body frame (meters).
          format: double
          example: 0.25
        name:
          type: string
          description: Operator-facing panel name.
          example: Port array
        panelIndex:
          type: integer
          description: Zero-based panel slot index within the spacecraft.
          format: int32
          example: 0
        rotationDeg:
          type: number
          description: Rotation about the mount axis (degrees). Range [0°, 360°).
          format: double
          example: 90
        specularReflection:
          type: number
          description: >-
            Per-panel optical specular-reflection coefficient ρs
            (dimensionless).
          format: double
          example: 0.2
        widthM:
          type: number
          description: Plate width (along the panel's local W axis) in meters.
          format: double
          example: 1
      description: >-
        One independent solar / radiator panel with its server-derived outward
        normal (DKR-1 §2 / §3.1).
    DerivedNormal:
      type: object
      properties:
        x:
          type: number
          description: Body-frame X component.
          format: double
          example: 1
        'y':
          type: number
          description: Body-frame Y component.
          format: double
          example: 0
        z:
          type: number
          description: Body-frame Z component.
          format: double
          example: 0
      description: A body-frame outward unit-normal triple {x, y, z}.
  securitySchemes:
    apiKeyAuth:
      description: 'API Key (format: vsp_sk_...)'
      scheme: bearer
      type: http

````