openapi: 3.1.0
info:
  title: Treblle Analytics Requests 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: Requests
  description: Access real-time API request and response logs captured by Treblle SDK instrumentation across all monitored APIs.
paths:
  /projects/{projectId}/requests:
    get:
      operationId: listRequests
      summary: List API Requests
      description: Returns a paginated list of API requests captured for the project. Includes request/response data, timing, status codes, and error info. Supports filtering by date range, status code, endpoint, and search terms.
      tags:
      - Requests
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number for pagination
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
        description: Number of requests per page
      - name: status_code
        in: query
        schema:
          type: integer
        description: Filter by HTTP status code
      - name: search
        in: query
        schema:
          type: string
        description: Search across URL, IP, and payload data
      - name: start_date
        in: query
        schema:
          type: string
          format: date
        description: Filter requests from this date (YYYY-MM-DD)
      - name: end_date
        in: query
        schema:
          type: string
          format: date
        description: Filter requests until this date (YYYY-MM-DD)
      responses:
        '200':
          description: Requests returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiRequest'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/requests/{requestId}:
    get:
      operationId: getRequest
      summary: Get API Request
      description: Retrieves the full details of a specific API request including headers, body, response, timing, and Treblle's analysis data points.
      tags:
      - Requests
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: requestId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Request details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRequestDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Request not found
components:
  schemas:
    ApiRequestDetail:
      type: object
      properties:
        id:
          type: string
        method:
          type: string
        url:
          type: string
        status_code:
          type: integer
        response_time:
          type: number
        ip_address:
          type: string
        request_headers:
          type: object
        request_body:
          type: object
        response_headers:
          type: object
        response_body:
          type: object
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              type:
                type: string
              source:
                type: string
        created_at:
          type: string
          format: date-time
    ApiRequest:
      type: object
      properties:
        id:
          type: string
          description: Unique request identifier
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
          - HEAD
          - OPTIONS
        url:
          type: string
          format: uri
        status_code:
          type: integer
        response_time:
          type: number
          description: Response time in milliseconds
        ip_address:
          type: string
        created_at:
          type: string
          format: date-time
        has_errors:
          type: boolean
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        last_page:
          type: integer
  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.