openapi.yaml

openapi: 3.1.0
info:
  title: Tracia API
  description: REST API for managing and running AI prompts with tracing
  version: 1.0.0
servers:
  - url: https://app.tracia.io/api/v1
    description: Production server
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key starting with `tr_`"
  schemas:
    Message:
      type: object
      required:
        - id
        - role
        - content
      properties:
        id:
          type: string
          description: Unique identifier for the message
        role:
          type: string
          enum: [system, user, assistant]
          description: Message role
        content:
          type: string
          description: Message content (may include `{{variables}}`)
    Prompt:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the prompt
        slug:
          type: string
          description: URL-friendly identifier
        name:
          type: string
          description: Display name of the prompt
        description:
          type: string
          nullable: true
          description: Description of the prompt
        provider:
          type: string
          nullable: true
          enum: [OPENAI, ANTHROPIC, GOOGLE, AMAZON_BEDROCK]
          description: Model provider
        model:
          type: string
          nullable: true
          description: Default model for this prompt
        temperature:
          type: number
          nullable: true
          description: Temperature setting for the model (0-2)
        topP:
          type: number
          nullable: true
          description: Top-p (nucleus) sampling setting (0-1)
        maxOutputTokens:
          type: integer
          nullable: true
          description: Maximum output tokens limit
        currentVersion:
          type: integer
          description: Current version number
        content:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Array of prompt messages
        variables:
          type: array
          items:
            type: string
          description: List of template variables extracted from content
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of creation
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last update
    PromptSummary:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        provider:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        temperature:
          type: number
          nullable: true
        topP:
          type: number
          nullable: true
        maxOutputTokens:
          type: integer
          nullable: true
        currentVersion:
          type: integer
        variables:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Span:
      type: object
      properties:
        id:
          type: string
          description: Internal identifier
        spanId:
          type: string
          description: External span ID (e.g., `sp_abc123`)
        traceId:
          type: string
          nullable: true
          description: Session/trace ID for multi-turn conversations
        parentSpanId:
          type: string
          nullable: true
          description: Parent span ID for chained conversations
        promptSlug:
          type: string
          nullable: true
          description: Slug of the prompt that was run (null for runLocal spans)
        promptVersion:
          type: integer
          nullable: true
          description: Version of the prompt used
        model:
          type: string
          description: Model used (e.g., `gpt-4o`)
        provider:
          type: string
          description: Provider name (e.g., `openai`, `amazon_bedrock`)
        input:
          type: object
          properties:
            messages:
              type: array
              items:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
        variables:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: Template variables used in the prompt
        output:
          type: string
          nullable: true
          description: Model response text
        status:
          type: string
          enum: [SUCCESS, ERROR]
        error:
          type: string
          nullable: true
          description: Error message if status is ERROR
        latencyMs:
          type: integer
          description: Execution time in milliseconds
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        totalTokens:
          type: integer
        cost:
          type: number
          nullable: true
          description: Cost in USD
        tags:
          type: array
          items:
            type: string
        userId:
          type: string
          nullable: true
        sessionId:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
    SpanSummary:
      type: object
      properties:
        id:
          type: string
        spanId:
          type: string
        traceId:
          type: string
          nullable: true
        promptSlug:
          type: string
          nullable: true
        model:
          type: string
        status:
          type: string
          enum: [SUCCESS, ERROR]
        latencyMs:
          type: integer
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        totalTokens:
          type: integer
        cost:
          type: number
          nullable: true
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Error message
    Evaluation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the evaluation
        evaluatorKey:
          type: string
          description: Key of the evaluator used
        evaluatorName:
          type: string
          description: Display name of the evaluator
        value:
          type: number
          description: The evaluation score
        source:
          type: string
          description: Source of the evaluation (e.g., `api`, `dashboard`)
        note:
          type: string
          nullable: true
          description: Optional note explaining the evaluation
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of creation
paths:
  /prompts:
    get:
      operationId: listPrompts
      summary: List Prompts
      description: Get all prompts for the authenticated user
      tags:
        - Prompts
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  prompts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PromptSummary'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createPrompt
      summary: Create Prompt
      description: Create a new prompt
      tags:
        - Prompts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - content
              properties:
                name:
                  type: string
                  description: Display name for the prompt
                slug:
                  type: string
                  description: URL-friendly identifier. Auto-generated from name if not provided.
                description:
                  type: string
                  description: Description of the prompt
                content:
                  type: array
                  items:
                    $ref: '#/components/schemas/Message'
                  description: Array of prompt messages
      responses:
        '201':
          description: Prompt created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict - slug already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /prompts/{slug}:
    get:
      operationId: getPrompt
      summary: Get Prompt
      description: Get a single prompt with its content
      tags:
        - Prompts
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: The prompt slug
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '404':
          description: Prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updatePrompt
      summary: Update Prompt
      description: Update an existing prompt. If the content changes, a new version is automatically created.
      tags:
        - Prompts
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: The prompt slug to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New display name
                slug:
                  type: string
                  description: New URL-friendly identifier
                description:
                  type: string
                  description: New description (set to empty string to clear)
                content:
                  type: array
                  items:
                    $ref: '#/components/schemas/Message'
                  description: New array of prompt messages
      responses:
        '200':
          description: Prompt updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '404':
          description: Prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict - new slug already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deletePrompt
      summary: Delete Prompt
      description: Delete a prompt and all its versions
      tags:
        - Prompts
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: The prompt slug to delete
      responses:
        '200':
          description: Prompt deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '404':
          description: Prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /prompts/{slug}/run:
    post:
      operationId: runPrompt
      summary: Run Prompt
      description: Execute a prompt and get the LLM response
      tags:
        - Prompts
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: The prompt slug to run
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: object
                  additionalProperties:
                    type: string
                  description: Key-value pairs for template variables
                model:
                  type: string
                  description: Override the default model (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
                version:
                  type: integer
                  description: Run a specific prompt version (uses latest if omitted)
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags for filtering spans in the dashboard
                userId:
                  type: string
                  description: End user identifier for tracking
                sessionId:
                  type: string
                  description: Session identifier for grouping related spans
                traceId:
                  type: string
                  description: Group related spans together (session ID for multi-turn conversations)
                parentSpanId:
                  type: string
                  description: Link to parent span (creates a chain)
                messages:
                  type: array
                  description: Full conversation messages for multi-turn (skips template rendering when provided)
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum: [system, developer, user, assistant, tool]
                      content:
                        type: string
                      tool_call_id:
                        type: string
                        description: Required when role is tool - the ID of the tool call being responded to
                      tool_name:
                        type: string
                        description: Required when role is tool - the name of the tool that was called
                      tool_calls:
                        type: array
                        description: Tool calls in assistant messages
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                              enum: [function]
                            function:
                              type: object
                              properties:
                                name:
                                  type: string
                                arguments:
                                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: The generated text from the LLM
                  spanId:
                    type: string
                    description: Unique identifier for this span
                  traceId:
                    type: string
                    description: Session identifier (same as spanId if not part of session)
                  promptVersion:
                    type: integer
                    description: Version of the prompt that was used
                  latencyMs:
                    type: integer
                    description: Total request latency in milliseconds
                  usage:
                    type: object
                    properties:
                      inputTokens:
                        type: integer
                      outputTokens:
                        type: integer
                      totalTokens:
                        type: integer
                  cost:
                    type: number
                    description: Estimated cost in USD
                  finishReason:
                    type: string
                    enum: [stop, max_tokens, tool_calls]
                    nullable: true
                    description: Why the model stopped generating
                  toolCalls:
                    type: array
                    nullable: true
                    description: Tool calls made by the model
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        arguments:
                          type: object
                  structuredOutput:
                    type: object
                    nullable: true
                    description: Parsed JSON when the prompt has an output schema configured
                  messages:
                    type: array
                    description: Full conversation messages for multi-turn continuation (input messages + assistant response)
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                          enum: [system, developer, user, assistant, tool]
                        content:
                          type: string
                        tool_call_id:
                          type: string
                        tool_name:
                          type: string
                        tool_calls:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              function:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  arguments:
                                    type: string
        '400':
          description: Bad request (missing variables or provider key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Provider error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /spans:
    get:
      operationId: listSpans
      summary: List Spans
      description: Get spans with optional filters and pagination
      tags:
        - Spans
      parameters:
        - name: promptSlug
          in: query
          schema:
            type: string
          description: Filter by prompt slug
        - name: status
          in: query
          schema:
            type: string
            enum: [SUCCESS, ERROR]
          description: Filter by status
        - name: startDate
          in: query
          schema:
            type: string
            format: date-time
          description: Filter spans created after this ISO 8601 date
        - name: endDate
          in: query
          schema:
            type: string
            format: date-time
          description: Filter spans created before this ISO 8601 date
        - name: userId
          in: query
          schema:
            type: string
          description: Filter by end user ID
        - name: sessionId
          in: query
          schema:
            type: string
          description: Filter by session ID
        - name: tags
          in: query
          schema:
            type: string
          description: Comma-separated list of tags (AND logic)
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Number of results per page (max 100, default 50)
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination (from previous response)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  spans:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpanSummary'
                  nextCursor:
                    type: string
                    nullable: true
                    description: Cursor for the next page of results
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /spans/{spanId}:
    get:
      operationId: getSpan
      summary: Get Span
      description: Get full details of a single span
      tags:
        - Spans
      parameters:
        - name: spanId
          in: path
          required: true
          schema:
            type: string
          description: The span ID (e.g., `sp_abc123def456`)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Span'
        '404':
          description: Span not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /spans/{spanId}/evaluations:
    post:
      operationId: evaluateSpan
      summary: Evaluate Span
      description: Submit an evaluation for a span. Evaluations allow you to score spans using custom evaluators.
      tags:
        - Spans
      parameters:
        - name: spanId
          in: path
          required: true
          schema:
            type: string
          description: The span ID to evaluate (e.g., `sp_abc123def456`)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - evaluatorKey
                - value
              properties:
                evaluatorKey:
                  type: string
                  description: The evaluator key. Currently only `quality` is supported.
                value:
                  type: number
                  description: The evaluation score. Use `1` for positive or `0` for negative.
                note:
                  type: string
                  description: Optional note explaining the evaluation
      responses:
        '201':
          description: Evaluation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
        '400':
          description: Invalid request (e.g., value is not a number)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Span not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'