openapi: 3.0.3
info:
  title: Gravitee.io APIM - Management API - Logs
  description: |
    This API allows to query logs data from the Gravitee.io APIM.

    The API provides access to:
    - **API Logs**: Detailed records of API connections at environment level.

  contact:
    name: DevX team
    email: team-gko@graviteesource.com
    url: https://www.gravitee.io/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
  - url: "/management/v2"
    description: APIM Management API v2 - Default base URL
  - url: "/management/v2/organizations/{orgId}"
    description: APIM Management API v2 - Base URL to target specific organizations
    variables:
      orgId:
        description: The unique ID of your organization
        default: DEFAULT

tags:
  - name: logs
    description: Operations related to querying API connection logs

paths:
  /environments/{envId}/logs/search:
    post:
      operationId: searchApiLogs
      summary: Search API logs
      description: |
        Retrieve API logs across the environment.
        Current implementation supports searching for v4 Proxy APIs logs.
      tags:
        - logs
      parameters:
        - $ref: "./openapi-analytics.yaml#/components/parameters/EnvId"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/perPageParam"
      requestBody:
        description: Search criteria including time range and optional filters
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchLogsRequest"
            examples:
              filter-by-api-and-http-status:
                summary: Logs for a specific API and HTTP statuses
                value:
                  timeRange:
                    from: "2025-01-01T00:00:00Z"
                    to: "2025-01-31T23:59:59Z"
                  filters:
                    - name: "API"
                      operator: "EQ"
                      value: "7b6ebef3-6236-4ac5-815e-d3dcef83df5d"
                    - name: "HTTP_STATUS"
                      operator: "IN"
                      value:
                        - "200"
                        - "404"
              filter-by-response-time-range:
                summary: Logs filtered by response time range (100ms to 500ms)
                value:
                  timeRange:
                    from: "2025-01-01T00:00:00Z"
                    to: "2025-01-31T23:59:59Z"
                  filters:
                    - name: "RESPONSE_TIME"
                      operator: "GTE"
                      value: 100
                    - name: "RESPONSE_TIME"
                      operator: "LTE"
                      value: 500
              filter-by-payload:
                summary: Logs filtered by request/response body content
                value:
                  timeRange:
                    from: "2025-01-01T00:00:00Z"
                    to: "2025-01-31T23:59:59Z"
                  filters:
                    - name: "PAYLOAD"
                      operator: "CONTAINS"
                      value: "error 500"
              filter-by-entrypoint:
                summary: Logs filtered by entrypoint
                value:
                  timeRange:
                    from: "2025-09-01T00:00:00Z"
                    to: "2026-01-31T23:59:59Z"
                  filters:
                    - name: "ENTRYPOINT"
                      operator: "IN"
                      value:
                        - "native-kafka"
                        - "websocket"
                        - "tcp-proxy"
                        - "sse"
                        - "agent-to-agent"
                        - "mcp-proxy"
                        - "mcp"
                        - "http-post"
                        - "http-proxy"
                        - "webhook"
                        - "llm-proxy"
                        - "http-get"

      responses:
        "200":
          description: List of connection logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchLogsResponse"
              example:
                data:
                  - requestId: "req-001"
                    apiId: "7b6ebef3-6236-4ac5-815e-d3dcef83df5d"
                    timestamp: "2025-01-15T10:30:00Z"
                    status: 200
                    method: "GET"
                    path: "/echo"
                    responseTime: 42
                    entrypoint: "http-proxy"
                pagination:
                  page: 1
                  perPage: 10
                  pageCount: 1
                  pageItemsCount: 1
                  totalCount: 1
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "./openapi-analytics.yaml#/components/schemas/Error"

  /environments/{envId}/logs/error-keys:
    get:
      operationId: getEnvironmentLogErrorKeys
      summary: Get environment error keys
      description: |
        Get the list of error keys found in the connection logs for the environment.
      tags:
        - logs
      parameters:
        - $ref: "./openapi-analytics.yaml#/components/parameters/EnvId"
        - $ref: "#/components/parameters/from"
        - $ref: "#/components/parameters/to"
      responses:
        "200":
          description: List of error keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["TIMEOUT", "GATEWAY_TIMEOUT"]
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "./openapi-analytics.yaml#/components/schemas/Error"

components:
  parameters:
    pageParam:
      name: page
      in: query
      required: false
      description: The page number for pagination.
      schema:
        type: integer
        default: 1
        minimum: 1
    perPageParam:
      name: perPage
      in: query
      required: false
      description: |
        The number of items per page for pagination.
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
    from:
      name: from
      in: query
      required: false
      description: |
        The timestamp from which the logs will be returned.
      schema:
        type: integer
        format: int64
    to:
      name: to
      in: query
      required: false
      description: |
        The timestamp to which the logs will be returned.
      schema:
        type: integer
        format: int64
  schemas:
    SearchLogsRequest:
      description: Request body for searching API connection logs
      type: object
      required:
        - timeRange
      properties:
        timeRange:
          $ref: "./openapi-analytics.yaml#/components/schemas/TimeRange"
        filters:
          type: array
          items:
            $ref: "#/components/schemas/Filter"
          description: Top-level filters
          example:
            - name: "API"
              operator: "EQ"
              value: "7b6ebef3-6236-4ac5-815e-d3dcef83df5d"
      example:
        timeRange:
          from: "2025-01-01T00:00:00Z"
          to: "2025-01-31T23:59:59Z"
        filters:
          - name: "API"
            operator: "EQ"
            value: "7b6ebef3-6236-4ac5-815e-d3dcef83df5d"

    SearchLogsResponse:
      description: Paginated response containing API connection logs
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EnvironmentApiLog"
          example:
            - requestId: "req-001"
              apiId: "7b6ebef3-6236-4ac5-815e-d3dcef83df5d"
              timestamp: "2025-01-15T10:30:00Z"
              status: 200
        pagination:
          allOf:
            - $ref: "./openapi-apis.yaml#/components/schemas/Pagination"
          example:
            page: 1
            perPage: 10
            pageCount: 1
            pageItemsCount: 1
            totalCount: 1
        links:
          allOf:
            - $ref: "./openapi-apis.yaml#/components/schemas/Links"
          example:
            self: "/environments/DEFAULT/logs/search?page=1&perPage=10"

    EnvironmentApiLog:
      type: object
      properties:
        apiId:
          type: string
          description: Id of the API.
          example: 6c530064-0b2c-4004-9300-640b2ce0047b
        apiName:
          type: string
          description: Name of the API.
          example: My API
        apiType:
          type: string
          description: The type of the API.
          enum:
            - HTTP_PROXY
            - LLM_PROXY
            - MCP_PROXY
        timestamp:
          type: string
          format: date-time
          description: The date (as timestamp) of the log.
          example: 2023-05-18T12:40:46.184Z
        id:
          type: string
          description: The internal UUID of the Log.
          example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
        requestId:
          type: string
          description: The id of the request.
          example: 1719d8d1-8d01-48f6-99d8-d18d0178f6d4
        method:
          $ref: "./openapi-apis.yaml#/components/schemas/HttpMethod"
        clientIdentifier:
          type: string
          description: The client identifier of the request.
          example: 12ca17b49af2289436f303e0166030a21e525d266e209267433801a8fd4071a0
        plan:
          $ref: "./openapi-apis.yaml#/components/schemas/BasePlan"
        application:
          $ref: "./openapi-apis.yaml#/components/schemas/BaseApplication"
        transactionId:
          type: string
          description: The id of the transaction.
          example: 00f8c9e7-78fc-4907-b8c9-e778fc790750
        status:
          type: integer
          description: The response's status.
          example: 200
        requestEnded:
          type: boolean
          description: The flag indicating if the request has ended.
          example: true
        gatewayResponseTime:
          type: integer
          description: The response time in ms
          example: 12
        gateway:
          type: string
          description: The gateway instance that processed the request.
          example: "API Gateway 1"
        uri:
          type: string
          description: URI of the request.
          example: /my-api
        endpoint:
          type: string
          description: The endpoint URL.
          example: "https://my-api-example.com"
        message:
          type: string
          description: The error message.
          example: "The timeout period of 1000ms has been exceeded"
        errorKey:
          type: string
          description: The error key.
          example: "TIMEOUT_ERROR"
        errorComponentName:
          type: string
          description: The name of the component that generated the error.
          example: "security"
        errorComponentType:
          type: string
          description: The type of the component that generated the error.
          example: "ENDPOINT"
        warnings:
          type: array
          description: The warning diagnostics
          items:
            $ref: "./openapi-apis.yaml#/components/schemas/ApiLogDiagnostic"
        additionalMetrics:
          type: object
          additionalProperties: true
          description: A map of string keys to values
        mcpMethod:
          type: string
          description: The MCP method invoked (MCP Proxy APIs only).
          example: "tools/list"
        apiProductId:
          type: string
          description: The ID of the API Product associated with this log entry. Absent when the request is not associated with any API Product.
          example: f5e6a5a0-1234-4b3a-9c1e-aabbccddeeff
        apiProductName:
          type: string
          description: The human-readable name of the API Product. Absent when no API Product is associated or the product cannot be resolved.
          example: My Partner API Product

    Filter:
      description: |
        Filters can be used refine the logs results.
      oneOf:
        - $ref: "#/components/schemas/StringFilter"
        - $ref: "#/components/schemas/ArrayFilter"
        - $ref: "#/components/schemas/NumericFilter"
      discriminator:
        propertyName: operator
        mapping:
          EQ: "#/components/schemas/StringFilter"
          CONTAINS: "#/components/schemas/StringFilter"
          IN: "#/components/schemas/ArrayFilter"
          GTE: "#/components/schemas/NumericFilter"
          LTE: "#/components/schemas/NumericFilter"
      example:
        name: "API"
        operator: "EQ"
        value: "7b6ebef3-6236-4ac5-815e-d3dcef83df5d"

    StringFilter:
      description: Filter specification for string values
      type: object
      required: [name, operator, value]
      properties:
        name:
          $ref: "#/components/schemas/FilterName"
        operator:
          $ref: "#/components/schemas/Operator"
        value:
          type: string
          description: Filter value (string for EQ)
      example: { name: "API", operator: "EQ", value: "api-id" }

    ArrayFilter:
      description: Filter specification for array values.
      type: object
      required: [name, operator, value]
      properties:
        name:
          $ref: "#/components/schemas/FilterName"
        operator:
          $ref: "#/components/schemas/Operator"
        value:
          type: array
          items:
            type: string
          description: Filter value (array for IN operator)
      example: { name: "HTTP_STATUS", operator: "IN", value: ["200", "301"] }

    NumericFilter:
      description: Filter specification for numeric values
      type: object
      required: [name, operator, value]
      properties:
        name:
          $ref: "#/components/schemas/FilterName"
        operator:
          $ref: "#/components/schemas/Operator"
        value:
          type: integer
          description: Filter value (number for GTE/LTE)
      example: { name: "RESPONSE_TIME", operator: "GTE", value: 100 }

    FilterName:
      type: string
      enum:
        - API
        - APPLICATION
        - ENTRYPOINT
        - PLAN
        - HTTP_METHOD
        - HTTP_STATUS
        - HTTP_STATUS_CODE_GROUP
        - HTTP_PATH
        - HTTP_GATEWAY_RESPONSE_TIME
        - MCP_PROXY_METHOD
        - TRANSACTION_ID
        - REQUEST_ID
        - ERROR_KEY
        - API_PRODUCT
        - API_TYPE
        - PAYLOAD
        - TENANT
        - MCP_METHOD
        - URI
        - RESPONSE_TIME
      description: |
        Available filter names for filtering connection logs.

        Prefer the names published by `GET /observability/filters/definition`, which are the ones this
        list is aligned on. `MCP_METHOD`, `URI` and `RESPONSE_TIME` are the historical spellings of
        `MCP_PROXY_METHOD`, `HTTP_PATH` and `HTTP_GATEWAY_RESPONSE_TIME`; they remain accepted so that
        links saved before the vocabularies were reconciled keep working.

    Operator:
      type: string
      enum:
        - EQ
        - GTE
        - LTE
        - IN
        - CONTAINS
      description: Filter operator