openapi: 3.1.0
info:
  title: Treblle 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.
  - name: Requests
    description: >-
      Access real-time API request and response logs captured by Treblle
      SDK instrumentation across all monitored APIs.
  - name: Analytics
    description: >-
      Retrieve performance metrics, usage statistics, error rates, and
      geographic distribution data for monitored APIs.
  - name: Governance
    description: >-
      Run automated API governance checks against OpenAPI specifications,
      scoring APIs on design, security, and performance dimensions.
  - name: Endpoints
    description: >-
      View auto-discovered endpoints detected by Treblle from live traffic,
      including documentation and schema data.
  - name: Members
    description: >-
      Manage project team members and access permissions.
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'
  /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
  /projects/{projectId}/analytics:
    get:
      operationId: getProjectAnalytics
      summary: Get Project Analytics
      description: >-
        Returns aggregated analytics for a project including total requests,
        error rates, average response time, top endpoints, geographic
        distribution, and device breakdown.
      tags:
        - Analytics
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Analytics start date (YYYY-MM-DD)
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: Analytics end date (YYYY-MM-DD)
      responses:
        '200':
          description: Analytics data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAnalytics'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/endpoints:
    get:
      operationId: listEndpoints
      summary: List Endpoints
      description: >-
        Returns auto-discovered endpoints detected from live API traffic for
        the project. Includes documentation data, request/response schemas,
        and endpoint performance metrics.
      tags:
        - Endpoints
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Endpoints returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Endpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/governance:
    post:
      operationId: runGovernanceCheck
      summary: Run Governance Check
      description: >-
        Runs Treblle's 30+ automated governance tests against an OpenAPI
        specification. Returns scores (1-100) and grades (A-F) across design,
        security, and performance categories.
      tags:
        - Governance
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GovernanceCheckRequest'
      responses:
        '200':
          description: Governance check results returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/members:
    get:
      operationId: listMembers
      summary: List Project Members
      description: Returns a list of team members with access to the project.
      tags:
        - Members
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Members returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: inviteMember
      summary: Invite Member
      description: Invites a team member to the project by email.
      tags:
        - Members
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteMemberRequest'
      responses:
        '201':
          description: Member invited successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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.
  schemas:
    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
    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]
    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
    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
    ProjectAnalytics:
      type: object
      properties:
        total_requests:
          type: integer
        error_rate:
          type: number
          description: Error rate as a percentage
        avg_response_time:
          type: number
          description: Average response time in milliseconds
        top_endpoints:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              method:
                type: string
              count:
                type: integer
        status_code_distribution:
          type: object
          description: Count of requests by HTTP status code range
        geographic_distribution:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              count:
                type: integer
    Endpoint:
      type: object
      properties:
        id:
          type: string
        path:
          type: string
        method:
          type: string
        total_calls:
          type: integer
        avg_response_time:
          type: number
        last_seen:
          type: string
          format: date-time
        has_documentation:
          type: boolean
    GovernanceCheckRequest:
      type: object
      required:
        - openapi_spec
      properties:
        openapi_spec:
          type: object
          description: The OpenAPI specification object to evaluate
    GovernanceResult:
      type: object
      properties:
        overall_score:
          type: integer
          minimum: 0
          maximum: 100
        overall_grade:
          type: string
          enum: [A, B, C, D, F]
        design_score:
          type: integer
        design_grade:
          type: string
        security_score:
          type: integer
        security_grade:
          type: string
        performance_score:
          type: integer
        performance_grade:
          type: string
        issues:
          type: array
          items:
            type: object
            properties:
              rule:
                type: string
              severity:
                type: string
                enum: [error, warning, info]
              message:
                type: string
              path:
                type: string
    Member:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, developer, viewer]
        joined_at:
          type: string
          format: date-time
    InviteMemberRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, developer, viewer]
          default: developer
    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