openapi: 3.1.0
info:
  title: APIClarity API Events Control API
  description: APIClarity is an open source API security and observability tool that analyzes API traffic to reconstruct OpenAPI specifications, detect shadow and zombie APIs, identify API differences and changes, and provide API security alerts. This is the REST API exposed by an APIClarity deployment.
  version: 1.0.0
  contact:
    name: OpenClarity
    url: https://github.com/openclarity/apiclarity
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/api
  description: Local APIClarity deployment
tags:
- name: Control
  description: Control-plane endpoints for trace sources and discovered APIs.
paths:
  /control/newDiscoveredAPIs:
    post:
      summary: Allows a client to notify APIClarity about new APIs.
      description: This allows a client (a gateway for example) to notify APIclarity about newly discovered APIs. If one of the APIs already exists, it is ignored.
      tags:
      - Control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - hosts
              properties:
                hosts:
                  type: array
                  description: List of discovered APIs, format of hostname:port
                  items:
                    type: string
        description: List of new discovered APIs
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/responses/Success'
        default:
          description: Response
  /control/traceSources:
    get:
      summary: List of configured trace sources
      tags:
      - Control
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - trace_sources
                properties:
                  trace_sources:
                    type: array
                    description: List of trace sources
                    items:
                      $ref: '#/components/schemas/TraceSource'
        default:
          description: Response
    post:
      summary: Create a new Trace Source
      tags:
      - Control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Create a new Trace Source
              $ref: '#/components/schemas/TraceSource'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceSource'
        default:
          description: Response
  /control/traceSources/{traceSourceId}:
    get:
      summary: Get Trace Source information
      tags:
      - Control
      parameters:
      - $ref: '#/components/parameters/traceSourceId'
      responses:
        '200':
          description: Trace Source information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceSource'
        '404':
          description: Trace Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        default:
          description: Response
    delete:
      summary: Delete a Trace Source
      tags:
      - Control
      parameters:
      - $ref: '#/components/parameters/traceSourceId'
      responses:
        '204':
          description: Success
        '404':
          description: Trace Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        default:
          description: Response
components:
  schemas:
    TraceSource:
      description: A Source which is sending traces to APIClarity
      type: object
      properties:
        id:
          type: integer
        uid:
          type: string
          format: uuid
        name:
          description: Unique name identifying a Trace Source
          type: string
        type:
          $ref: '#/components/schemas/TraceSourceType'
        description:
          type: string
        token:
          type: string
      required:
      - name
      - type
    ApiResponse:
      description: An object that is return in all cases of failures.
      type: object
      properties:
        message:
          type: string
    TraceSourceType:
      type: string
      enum:
      - APIGEE_X
      - F5_BIG_IP
      - KONG_INTERNAL
      - TYK_INTERNAL
  parameters:
    traceSourceId:
      name: traceSourceId
      in: path
      required: true
      description: Trace Source ID
      schema:
        type: string
        format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: APIClarity is typically deployed inside a Kubernetes cluster behind an ingress that enforces authentication. When exposed externally, deployments commonly require a bearer token.