Trajectory Telemetry API

openapi: 3.2.0
info:
  title: Trajectory Telemetry API
  version: 0.1.0
  x-trajectory-api-version: '2026-10-14'
  description: This contract is API version 2026-10-14. The optional Trajectory-API-Version header pins it, and tmp-contract is accepted as an alias. Requests without the header get this version. Version 2026-10-07 and the pre-launch legacy response formats are retired.
tags:
- name: Telemetry
paths:
  /api/v1/telemetry/events:
    post:
      tags:
      - Telemetry
      summary: Ingest Events
      operationId: ingestTelemetryEvents
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryEventsIngestRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryEventsIngestResponse'
        '207':
          description: Some telemetry event batches were accepted, but one or more failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryEventsIngestResponse'
      x-trajectory-visibility: public
components:
  schemas:
    TelemetryEventsIngestResponse:
      properties:
        ingested:
          type: integer
          title: Ingested
          description: Number of telemetry events accepted for ingestion.
        skipped:
          type: integer
          title: Skipped
          description: Number of telemetry events skipped by validation.
          default: 0
        failures:
          items:
            $ref: '#/components/schemas/BatchItemFailure'
          type: array
          title: Failures
          description: Structured batch-level ingestion failures, if any.
      type: object
      required:
      - ingested
      title: TelemetryEventsIngestResponse
    TelemetryEventIngestRequest:
      properties:
        event_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Event Id
          description: Caller-provided unique event id used for idempotency and deduplication.
        event_type:
          type: string
          maxLength: 256
          minLength: 1
          title: Event Type
          description: Product-defined telemetry event name, such as 'tool_call' or 'user_accept'.
        timestamp:
          type: string
          minLength: 1
          title: Timestamp
          description: ISO 8601 timestamp for when the event occurred.
        session_id:
          type: string
          maxLength: 512
          minLength: 1
          title: Session Id
          description: Grouping key for a broader user session, eval run, or import job.
        source:
          type: string
          maxLength: 128
          minLength: 1
          title: Source
          description: Origin of the event, such as 'sdk', 'api', 'training', or 'synthetic'.
        user_id:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: User Id
          description: End-user identifier from the caller's system, when available.
        trajectory_id:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Trajectory Id
          description: Stored trajectory id returned by trajectory upload, when already known.
        trace_id:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Trace Id
          description: Caller-owned correlation key shared by telemetry and its trajectory.
        properties:
          additionalProperties: true
          type: object
          title: Properties
          description: Event-specific JSON properties.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Additional metadata for debugging, SDK versions, or ingestion context.
      type: object
      required:
      - event_id
      - event_type
      - timestamp
      - session_id
      - source
      title: TelemetryEventIngestRequest
    TelemetryEventsIngestRequest:
      properties:
        events:
          items:
            $ref: '#/components/schemas/TelemetryEventIngestRequest'
          type: array
          maxItems: 100000
          minItems: 1
          title: Events
          description: Telemetry events to ingest.
      type: object
      required:
      - events
      title: TelemetryEventsIngestRequest
    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
  securitySchemes:
    TrajectoryAccessToken:
      type: http
      description: Short-lived token scoped to one rollout trajectory
      scheme: bearer
    InferenceAuthorization:
      type: http
      scheme: bearer