openapi: 3.1.0
info:
  title: CounterAgent API
  description: |
    AI agent detection and fingerprinting platform. Identify, classify,
    and monitor autonomous AI agents interacting with your infrastructure.

    CounterAgent maintains the largest database of AI agent TLS/HTTP
    fingerprints, covering major frameworks including LangChain, CrewAI,
    AutoGPT, Claude API, OpenAI SDK, and browser-based agents.
  version: 1.0.0
  contact:
    email: api@counteragent.io
    url: https://docs.counteragent.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.counteragent.io/v1
    description: Production
  - url: https://api.counteragent.io/v2
    description: Beta

security:
  - bearerAuth: []

paths:
  /detect:
    post:
      operationId: detectAgent
      summary: Detect if a request originates from an AI agent
      description: |
        Analyzes request metadata (headers, TLS fingerprint, behavioural
        signals) to determine if the request was made by an AI agent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_agent:
                  type: string
                  description: HTTP User-Agent header
                ja4:
                  type: string
                  description: JA4 TLS fingerprint
                ja4h:
                  type: string
                  description: JA4H HTTP fingerprint
                headers:
                  type: object
                  description: Full HTTP header map
      responses:
        '200':
          description: Detection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectionResult'

  /fingerprint/lookup:
    get:
      operationId: lookupFingerprint
      summary: Look up a JA4/JA4S/JA4H fingerprint
      parameters:
        - name: ja4
          in: query
          schema:
            type: string
        - name: ja4s
          in: query
          schema:
            type: string
        - name: ja4h
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Matching signatures
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Signature'

  /agents:
    get:
      operationId: listAgents
      summary: List known AI agent frameworks and their fingerprints
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [llm-sdk, browser-agent, orchestrator, crawler, custom]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: List of known agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
                  total:
                    type: integer

  /signatures:
    get:
      operationId: listSignatures
      summary: Browse the signature database
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [ja4, ja4s, ja4h, ja4x]
        - name: unknown_only
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Signature list

  /webhooks:
    post:
      operationId: registerWebhook
      summary: Register a webhook for new agent detection alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum: [new_agent, new_signature, threat_detected]
      responses:
        '201':
          description: Webhook registered

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    DetectionResult:
      type: object
      properties:
        is_agent:
          type: boolean
        confidence:
          type: number
          format: float
        agent_name:
          type: string
        agent_category:
          type: string
        fingerprints:
          type: object
          properties:
            ja4:
              type: string
            ja4s:
              type: string
            ja4h:
              type: string

    Signature:
      type: object
      properties:
        fingerprint:
          type: string
        type:
          type: string
        agent_name:
          type: string
        first_seen:
          type: string
          format: date-time
        confidence:
          type: number

    Agent:
      type: object
      properties:
        name:
          type: string
        category:
          type: string
        fingerprints:
          type: object
        first_seen:
          type: string
          format: date-time
        description:
          type: string