openapi: 3.1.0
info:
  title: LangWatch Agents LangWatch API API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
- url: https://app.langwatch.ai
security:
- project_api_key: []
tags:
- name: LangWatch API
paths:
  /:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    handle:
                      type:
                      - string
                      - 'null'
                    scope:
                      type: string
                      enum:
                      - ORGANIZATION
                      - PROJECT
                    name:
                      type: string
                    updatedAt:
                      type: string
                    projectId:
                      type: string
                    organizationId:
                      type: string
                    version:
                      type: number
                    versionId:
                      type: string
                    versionCreatedAt:
                      type: string
                    model:
                      type: string
                    prompt:
                      type: string
                    messages:
                      type: array
                      items:
                        type: object
                        properties:
                          role:
                            type: string
                            enum:
                            - user
                            - assistant
                            - system
                          content:
                            type: string
                        required:
                        - role
                        - content
                    response_format:
                      type:
                      - object
                      - 'null'
                      properties:
                        type:
                          type: string
                          enum:
                          - json_schema
                        json_schema:
                          type: object
                          properties:
                            name:
                              type: string
                            schema:
                              type: object
                          required:
                          - name
                          - schema
                      required:
                      - type
                      - json_schema
                  required:
                  - id
                  - handle
                  - scope
                  - name
                  - updatedAt
                  - projectId
                  - organizationId
                  - version
                  - versionId
                  - versionCreatedAt
                  - model
                  - prompt
                  - messages
                  - response_format
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getIndex
      parameters: []
      description: Get all prompts for a project
      tags:
      - LangWatch API
    post:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  handle:
                    type:
                    - string
                    - 'null'
                  scope:
                    type: string
                    enum:
                    - ORGANIZATION
                    - PROJECT
                  name:
                    type: string
                  updatedAt:
                    type: string
                  projectId:
                    type: string
                  organizationId:
                    type: string
                  version:
                    type: number
                  versionId:
                    type: string
                  versionCreatedAt:
                    type: string
                  model:
                    type: string
                  prompt:
                    type: string
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                          enum:
                          - user
                          - assistant
                          - system
                        content:
                          type: string
                      required:
                      - role
                      - content
                  response_format:
                    type:
                    - object
                    - 'null'
                    properties:
                      type:
                        type: string
                        enum:
                        - json_schema
                      json_schema:
                        type: object
                        properties:
                          name:
                            type: string
                          schema:
                            type: object
                        required:
                        - name
                        - schema
                    required:
                    - type
                    - json_schema
                required:
                - id
                - handle
                - scope
                - name
                - updatedAt
                - projectId
                - organizationId
                - version
                - versionId
                - versionCreatedAt
                - model
                - prompt
                - messages
                - response_format
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postIndex
      parameters: []
      description: Create a new prompt with default initial version
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  pattern: ^[a-z0-9_-]+(?:\/[a-z0-9_-]+)?$
                scope:
                  type: string
                  enum:
                  - ORGANIZATION
                  - PROJECT
                  default: PROJECT
                authorId:
                  type: string
                prompt:
                  type: string
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                        - user
                        - assistant
                        - system
                      content:
                        type: string
                    required:
                    - role
                    - content
                inputs:
                  type: array
                  items:
                    type: object
                    properties:
                      identifier:
                        type: string
                        minLength: 1
                      type:
                        type: string
                        enum:
                        - str
                        - float
                        - bool
                        - image
                        - list[str]
                        - list[float]
                        - list[int]
                        - list[bool]
                        - dict
                    required:
                    - identifier
                    - type
                outputs:
                  type: array
                  items:
                    type: object
                    properties:
                      identifier:
                        type: string
                        minLength: 1
                      type:
                        type: string
                        enum:
                        - str
                        - float
                        - bool
                        - json_schema
                      json_schema:
                        type: object
                        properties:
                          type:
                            type: string
                            minLength: 1
                        required:
                        - type
                        additionalProperties: true
                    required:
                    - identifier
                    - type
              required:
              - handle
      tags:
      - LangWatch API
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: 'Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.'
    admin_api_key:
      type: http
      scheme: bearer
      description: 'Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.'