openapi: 3.1.0
info:
  title: Treblle Analytics Projects API
  description: The Treblle API provides programmatic access to the Treblle API Intelligence Platform, enabling teams to manage projects, retrieve API request logs, access analytics, run governance checks, and integrate Treblle into CI/CD pipelines. Treblle analyzes 40+ API-specific data points for every request, providing real-time observability, security scanning, and auto-generated documentation. Authentication uses API Key passed as a header.
  version: 1.0.0
  contact:
    name: Treblle Support
    url: https://treblle.com
  license:
    name: Proprietary
    url: https://treblle.com/terms-of-service
servers:
- url: https://app.treblle.com/api/v1
  description: Treblle Platform API
security:
- apiKeyAuth: []
tags:
- name: Projects
  description: Create and manage Treblle API projects. Each project corresponds to a monitored API and generates an API ID and SDK token.
paths:
  /projects:
    get:
      operationId: listProjects
      summary: List Projects
      description: Returns a list of all API projects in the workspace. Each project corresponds to a monitored API with its own API ID and SDK token.
      tags:
      - Projects
      responses:
        '200':
          description: Projects returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      summary: Create Project
      description: Creates a new API project in Treblle. Returns the project including the API ID and SDK token needed for SDK instrumentation.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}:
    get:
      operationId: getProject
      summary: Get Project
      description: Retrieves details of a specific Treblle project by its ID, including configuration, API ID, and current monitoring statistics.
      tags:
      - Projects
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier for the project
      responses:
        '200':
          description: Project returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Project not found
    put:
      operationId: updateProject
      summary: Update Project
      description: Updates a Treblle project's configuration including name, description, and environment settings.
      tags:
      - Projects
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteProject
      summary: Delete Project
      description: Deletes a Treblle project and all associated data.
      tags:
      - Projects
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Project deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateProjectRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        environment:
          type: string
          enum:
          - development
          - staging
          - production
          default: production
    UpdateProjectRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        environment:
          type: string
          enum:
          - development
          - staging
          - production
    Project:
      type: object
      properties:
        id:
          type: string
          description: Unique project identifier
        name:
          type: string
          description: Project display name
        description:
          type: string
          description: Project description
        api_id:
          type: string
          description: Unique API ID for SDK instrumentation
        sdk_token:
          type: string
          description: SDK token for authenticating Treblle SDKs
        environment:
          type: string
          enum:
          - development
          - staging
          - production
          description: The environment this project monitors
        total_requests:
          type: integer
          description: Total number of requests captured
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Authentication failed. API key missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Treblle-Api-Key
      description: Treblle API key obtained from the Treblle workspace settings. Pass the API key in the Treblle-Api-Key header.