---
title: "Upload"
method: POST
path: "/api/v1/trajectories/upload"
tags: ["trajectories"]
---

# Upload

`POST /api/v1/trajectories/upload`

## Headers

- `X-API-Key` string, required

## Request body

- TrajectoryUploadRequest
  - `dataset` string, required — Dataset name to upload these trajectories into.
  - `trajectories` object[] — Trajectory payloads to validate, store, and index.

## Response `200`

Successful Response

- TrajectoryUploadResponse
  - `uploaded` integer, required — Number of trajectories accepted for storage.
  - `skipped` integer, required — Number of trajectories skipped by validation or deduplication.
  - `failures` BatchItemFailure[] — Structured batch-level upload failures, if any.
    - `code` string, required — Stable programmatic reason for this item failure.
    - `message` string, required — Human-readable explanation for this item occurrence.
    - `item_index` integer, nullable — Zero-based input index when the failed item came from a list.
    - `context` object — Machine-readable values specific to this failure code.
  - `message` string, nullable — Human-readable upload summary.
  - `partial_success` boolean — True when some trajectories uploaded but one or more errors occurred.
  - `trajectories` TrajectoryUploadItem[] — Per-trajectory upload mapping for correlating caller ids to trajectory ids.
    - `request_index` integer, required — Zero-based index of this trajectory in the request.
    - `conversation_id` string, nullable — Caller-provided conversation id from task.conversation_id.
    - `trace_id` string, nullable — Caller-owned correlation key shared by telemetry and this trajectory.
    - `trajectory_id` string, nullable — Stored trajectory id assigned by the backend.
    - `model_id` string, nullable — Internal model id associated with this trajectory, when known.
    - `model_association_source` string, nullable — How the trajectory was associated with a model.
    - `status` 'uploaded' | 'skipped' | 'error', required — Upload status for this trajectory: uploaded, skipped, or error.
    - `failure` BatchItemFailure
      - `code` string, required — Stable programmatic reason for this item failure.
      - `message` string, required — Human-readable explanation for this item occurrence.
      - `item_index` integer, nullable — Zero-based input index when the failed item came from a list.
      - `context` object — Machine-readable values specific to this failure code.

## Other responses

- `207` — Some trajectories were accepted, but one or more items failed.

---

[API](https://skmtc.dev/trajectory/apis/trajectory-api.md) · [All operations](https://skmtc.dev/trajectory/apis/trajectory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trajectory/trajectory-api/revisions/d930b23b9602/schema)