> ## 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.

# Add an MA-scoped payload

> Adds a payload under a parent spacecraft resolved strictly by id within the MISSION_ANALYSIS environment. 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 craft lives in a different environment.



## OpenAPI

````yaml https://api.valar.space/api-docs/mintlify post /mission-analysis/spacecraft/{spacecraftId}/payloads
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:
  /mission-analysis/spacecraft/{spacecraftId}/payloads:
    post:
      tags:
        - Mission Analysis Payloads
      summary: Add an MA-scoped payload
      description: >-
        Adds a payload under a parent spacecraft resolved strictly by id within
        the MISSION_ANALYSIS environment. 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 craft lives in a
        different environment.
      operationId: createMissionAnalysisPayload
      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 MA env access or PERM_write:spacecraft
            permission
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Parent spacecraft not found in MA scope
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payload limit exceeded (8-sensor cap)
      security:
        - bearerAuth: []
components:
  schemas:
    PayloadRequest:
      required:
        - boresight
        - fovShape
        - name
        - positionX
        - positionY
        - positionZ
      type: object
      properties:
        boresight:
          type: string
          description: Body-frame boresight axis. One of X+, X-, Y+, Y-, Z+, Z-.
          example: Z+
          enum:
            - X+
            - X-
            - Y+
            - Y-
            - Z+
            - Z-
        fovShape:
          type: string
          description: >-
            Field-of-view shape primitive (CONICAL, RECTANGULAR, ELLIPTICAL,
            POLYGON). Determines which conditional shape parameters are
            required.
          example: CONICAL
          enum:
            - CONICAL
            - RECTANGULAR
            - ELLIPTICAL
            - POLYGON
        halfAngleDeg:
          maximum: 90
          exclusiveMaximum: false
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: >-
            Cone half-angle in degrees (CONICAL only). Range (0°, 90°]; 90°
            accepted.
          format: double
          example: 30
        halfHeightDeg:
          maximum: 90
          exclusiveMaximum: true
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: >-
            FOV half-height in degrees (RECTANGULAR / ELLIPTICAL only). Range
            (0°, 90°) strict.
          format: double
          example: 20
        halfWidthDeg:
          maximum: 90
          exclusiveMaximum: true
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: >-
            FOV half-width in degrees (RECTANGULAR / ELLIPTICAL only). Range
            (0°, 90°) strict.
          format: double
          example: 10
        name:
          maxLength: 100
          minLength: 0
          type: string
          description: Operator-supplied payload name.
          example: EO Camera
        positionX:
          type: number
          description: Payload mounting position X in metres (body frame; may be negative).
          format: double
          example: 0.1
        positionY:
          type: number
          description: Payload mounting position Y in metres (body frame; may be negative).
          format: double
          example: 0
        positionZ:
          type: number
          description: Payload mounting position Z in metres (body frame; may be negative).
          format: double
          example: -0.2
        radiusDeg:
          maximum: 90
          exclusiveMaximum: true
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: >-
            Polygon circumscribed (to-vertices) angular radius in degrees
            (POLYGON only). Range (0°, 90°) strict. Datum =
            OUTSIDE_CONE_TOUCHING_POLYGON_AT_VERTICES (DA-3).
          format: double
          example: 30
        sides:
          maximum: 1000
          minimum: 3
          type: integer
          description: Number of polygon sides (POLYGON only). 3 ≤ N ≤ 1000.
          format: int32
          example: 6
      description: >-
        One payload (sensor): boresight axis + four-shape field of view (DKR-1
        §3.3).
      nullable: true
    PayloadResponse:
      type: object
      properties:
        boresight:
          type: string
          enum:
            - X+
            - X-
            - Y+
            - Y-
            - Z+
            - Z-
        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
        payloadIndex:
          type: integer
          format: int32
        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
    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)
  securitySchemes:
    apiKeyAuth:
      description: 'API Key (format: vsp_sk_...)'
      scheme: bearer
      type: http

````