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

# Upload



## OpenAPI

````yaml /openapi.json post /api/v1/trajectories/upload
openapi: 3.1.0
info:
  title: Trajectory API
  version: 0.1.0
servers:
  - url: https://api.trajectory.ai
security: []
paths:
  /api/v1/trajectories/upload:
    post:
      tags:
        - trajectories
      summary: Upload
      operationId: uploadTrajectories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrajectoryUploadRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrajectoryUploadResponse'
        '207':
          description: Some trajectories were accepted, but one or more items failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrajectoryUploadResponse'
        '400':
          description: No trajectories were accepted because the upload is invalid.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Trajectory-Should-Retry:
              $ref: '#/components/headers/TrajectoryShouldRetry'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTrajectoryUploadErrorResponse'
        '409':
          description: No trajectories were accepted because their content conflicts.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Trajectory-Should-Retry:
              $ref: '#/components/headers/TrajectoryShouldRetry'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrajectoryUploadConflictErrorResponse'
        '500':
          description: No trajectories were accepted because storage failed.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Trajectory-Should-Retry:
              $ref: '#/components/headers/TrajectoryShouldRetry'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrajectoryUploadFailedErrorResponse'
        default:
          $ref: '#/components/responses/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TrajectoryUploadRequest:
      properties:
        dataset:
          type: string
          maxLength: 256
          minLength: 1
          title: Dataset
          description: Dataset name to upload these trajectories into.
        trajectories:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 100000
          title: Trajectories
          description: Trajectory payloads to validate, store, and index.
      type: object
      required:
        - dataset
      title: TrajectoryUploadRequest
    TrajectoryUploadResponse:
      properties:
        uploaded:
          type: integer
          title: Uploaded
          description: Number of trajectories accepted for storage.
        skipped:
          type: integer
          title: Skipped
          description: Number of trajectories skipped by validation or deduplication.
        failures:
          items:
            $ref: '#/components/schemas/BatchItemFailure'
          type: array
          title: Failures
          description: Structured batch-level upload failures, if any.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Human-readable upload summary.
        partial_success:
          type: boolean
          title: Partial Success
          description: >-
            True when some trajectories uploaded but one or more errors
            occurred.
          default: false
        trajectories:
          items:
            $ref: '#/components/schemas/TrajectoryUploadItem'
          type: array
          title: Trajectories
          description: >-
            Per-trajectory upload mapping for correlating caller ids to
            trajectory ids.
      type: object
      required:
        - uploaded
        - skipped
      title: TrajectoryUploadResponse
    InvalidTrajectoryUploadErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/InvalidTrajectoryUploadErrorBody'
      type: object
      required:
        - error
      title: InvalidTrajectoryUploadErrorResponse
    TrajectoryUploadConflictErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/TrajectoryUploadConflictErrorBody'
      type: object
      required:
        - error
      title: TrajectoryUploadConflictErrorResponse
    TrajectoryUploadFailedErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/TrajectoryUploadFailedErrorBody'
      type: object
      required:
        - error
      title: TrajectoryUploadFailedErrorResponse
    BatchItemFailure:
      properties:
        code:
          type: string
          title: Code
          description: Stable programmatic reason for this item failure.
        message:
          type: string
          title: Message
          description: Human-readable explanation for this item occurrence.
        item_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Item Index
          description: Zero-based input index when the failed item came from a list.
        context:
          additionalProperties: true
          type: object
          title: Context
          description: Machine-readable values specific to this failure code.
      type: object
      required:
        - code
        - message
      title: BatchItemFailure
    TrajectoryUploadItem:
      properties:
        request_index:
          type: integer
          title: Request Index
          description: Zero-based index of this trajectory in the request.
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: Caller-provided conversation id from task.conversation_id.
        trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Trace Id
          description: >-
            Caller-owned correlation key shared by telemetry and this
            trajectory.
        trajectory_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Trajectory Id
          description: Stored trajectory id assigned by the backend.
        model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Id
          description: Internal model id associated with this trajectory, when known.
        model_association_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Association Source
          description: How the trajectory was associated with a model.
        status:
          type: string
          title: Status
          description: 'Upload status for this trajectory: uploaded, skipped, or error.'
        failure:
          anyOf:
            - $ref: '#/components/schemas/BatchItemFailure'
            - type: 'null'
          description: Structured trajectory-specific failure, if any.
      type: object
      required:
        - request_index
        - status
      title: TrajectoryUploadItem
    InvalidTrajectoryUploadErrorBody:
      properties:
        type:
          type: string
          const: invalid_request_error
          title: Type
        code:
          type: string
          const: invalid_trajectory_upload
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          $ref: '#/components/schemas/TrajectoryUploadFailureContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: InvalidTrajectoryUploadErrorBody
    TrajectoryUploadConflictErrorBody:
      properties:
        type:
          type: string
          const: conflict_error
          title: Type
        code:
          type: string
          const: trajectory_upload_conflict
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          $ref: '#/components/schemas/TrajectoryUploadFailureContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: TrajectoryUploadConflictErrorBody
    TrajectoryUploadFailedErrorBody:
      properties:
        type:
          type: string
          const: api_error
          title: Type
        code:
          type: string
          const: trajectory_upload_failed
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          $ref: '#/components/schemas/TrajectoryUploadFailureContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: TrajectoryUploadFailedErrorBody
    ApiErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      required:
        - error
      title: ApiErrorEnvelope
      type: object
    TrajectoryUploadFailureContext:
      properties:
        failures:
          items:
            $ref: '#/components/schemas/BatchItemFailure'
          type: array
          title: Failures
      additionalProperties: false
      type: object
      required:
        - failures
      title: TrajectoryUploadFailureContext
    ApiErrorBody:
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        code:
          title: Code
          type: string
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          additionalProperties: true
          title: Context
          type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: ApiErrorBody
      type: object
    ErrorType:
      enum:
        - invalid_request_error
        - authentication_error
        - permission_error
        - conflict_error
        - rate_limit_error
        - dependency_error
        - api_error
      title: ErrorType
      type: string
  headers:
    RequestId:
      schema:
        type: string
    TrajectoryShouldRetry:
      schema:
        type: boolean
    RetryAfter:
      schema:
        type: string
  responses:
    ApiErrorResponse:
      description: >-
        Common API error. Possible codes: `authentication_required`,
        `permission_denied`, `validation_error`, `rate_limited`,
        `internal_error`, `service_unavailable`.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Trajectory-Should-Retry:
          $ref: '#/components/headers/TrajectoryShouldRetry'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Organization API key

````