Trajectory Secrets API

openapi: 3.2.0
info:
  title: Trajectory Secrets 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: Secrets
paths:
  /api/v1/secrets:
    get:
      tags:
      - Secrets
      summary: List User Secrets
      operationId: listUserSecrets
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 25
          title: Limit
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          default: desc
          title: Order
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretListResponse'
      x-trajectory-visibility: public
    post:
      tags:
      - Secrets
      summary: Create Secret
      operationId: createSecret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSecretResponse'
      x-trajectory-visibility: public
  /api/v1/secrets/{secret_id}:
    delete:
      tags:
      - Secrets
      summary: Revoke Secret
      operationId: revokeSecret
      parameters:
      - name: secret_id
        in: path
        required: true
        schema:
          type: string
          title: Secret Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeSecretResponse'
      x-trajectory-visibility: public
components:
  schemas:
    SecretListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Secret'
          type: array
          title: Items
          description: Page of the organization's live secrets.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Cursor for the next page, or null if none.
        has_more:
          type: boolean
          title: Has More
          description: True if more secrets remain beyond this page.
      type: object
      required:
      - items
      - has_more
      title: SecretListResponse
    Secret:
      properties:
        secret_id:
          type: string
          title: Secret Id
          description: Opaque identifier used to reference the secret.
        name:
          type: string
          title: Name
          description: Name the secret is referenced by (e.g. in ${secret:NAME}).
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional human-readable description.
        byte_length:
          type: integer
          title: Byte Length
          description: Length of the secret value in UTF-8 bytes.
        created_at:
          anyOf:
          - type: string
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: UTC timestamp the secret was created.
        updated_at:
          anyOf:
          - type: string
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: UTC timestamp the secret was last updated.
      type: object
      required:
      - secret_id
      - name
      - byte_length
      title: Secret
    CreateSecretResponse:
      properties:
        secret:
          $ref: '#/components/schemas/Secret'
          description: Metadata for the newly created secret.
      type: object
      required:
      - secret
      title: CreateSecretResponse
    CreateSecretRequest:
      properties:
        name:
          type: string
          title: Name
          description: Name to reference the secret by; unique among live secrets.
        value:
          type: string
          title: Value
          description: The secret value. Write-only — never returned after creation.
        description:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Description
          description: Optional human-readable description.
      type: object
      required:
      - name
      - value
      title: CreateSecretRequest
    RevokeSecretResponse:
      properties:
        secret_id:
          type: string
          title: Secret Id
          description: Identifier of the secret that was revoked.
      type: object
      required:
      - secret_id
      title: RevokeSecretResponse
  securitySchemes:
    TrajectoryAccessToken:
      type: http
      description: Short-lived token scoped to one rollout trajectory
      scheme: bearer
    InferenceAuthorization:
      type: http
      scheme: bearer