Kaminari Ad Alerts API

openapi: 3.2.0
info:
  title: Kaminari Ad Alerts API
  description: 'REST API for Kaminari Ad, the ad quality and ad security platform for publishers, ad networks, SSPs and DSPs. Submit ad creatives, ad tags and landing pages for scanning, read verdicts with evidence, manage policies, alerts and webhooks.


    Authenticate with an API key as a Bearer token: https://kaminari.ad/docs/developers/authentication'
  contact:
    name: Kaminari Ad Support
    url: https://kaminari.ad/contact
    email: support@kaminari.ad
  version: 0.1.0
servers:
- url: https://app.kaminari.ad
tags:
- name: Alerts
paths:
  /api/v1/alerts:
    get:
      tags:
      - Alerts
      summary: List Alerts
      description: 'List alerts for the caller''s organization with pagination + filters.


        ``policy_set_id``, ``tag`` and ``country_code`` accept comma-separated

        values and match alerts carrying any of them. ``date_from``/``date_to``

        are inclusive calendar dates interpreted in ``timezone`` and bound

        ``created_at``; omitting both lists all time.


        ``limit`` is capped at 200; requests above that return 422 rather

        than a silently downgraded response. Iterate through all results

        using ``page``/``limit`` and the returned ``total``/``pages``.


        Note: ``offset`` was removed in favour of ``page`` — sending

        ``offset`` has no effect.'
      operationId: list_alerts_api_v1_alerts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Campaign Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AlertStatus'
          - type: 'null'
          title: Status
      - name: policy_set_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Policy Set Id
      - name: tag
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tag
      - name: country_code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Code
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: timezone
        in: query
        required: false
        schema:
          type: string
          default: UTC
          title: Timezone
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_AlertResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/alerts/{alert_id}/status:
    patch:
      tags:
      - Alerts
      summary: Update Alert Status
      description: Update an alert's status.
      operationId: update_alert_status_api_v1_alerts__alert_id__status_patch
      security:
      - HTTPBearer: []
      parameters:
      - name: alert_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Alert Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlertStatusRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/alerts/bulk-status:
    post:
      tags:
      - Alerts
      summary: Bulk Update Alert Status
      description: 'Change status for many alerts at once.


        Provide either an explicit ``ids`` list or ``all_matching=true`` with

        the optional ``filter_*`` fields, which mirror this endpoint''s list

        filters. Alerts already in a non-transitionable state are skipped.

        Returns updated/skipped counts.'
      operationId: bulk_update_alert_status_api_v1_alerts_bulk_status_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateAlertStatusRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateAlertStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/alerts/stats:
    get:
      tags:
      - Alerts
      summary: Get Alert Stats
      description: 'Get alert counts grouped by status.


        Accepts every filter the list endpoint does except ``status`` — the

        response buckets by status, so the four counts sum to the ``total``

        that ``GET /api/v1/alerts`` reports for the same query. Omitting the

        dates means all time, matching the list endpoint; it previously meant

        the last 30 days, which broke that sum.'
      operationId: get_alert_stats_api_v1_alerts_stats_get
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Campaign Id
      - name: policy_set_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Policy Set Id
      - name: tag
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tag
      - name: country_code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Code
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Date To
      - name: timezone
        in: query
        required: false
        schema:
          type: string
          default: UTC
          title: Timezone
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AlertStatus:
      type: string
      enum:
      - open
      - escalated
      - resolved
      - dismissed
      title: AlertStatus
      description: Lifecycle status of a policy-violation alert.
    AlertResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        scan_id:
          type: string
          format: uuid
          title: Scan Id
        campaign_id:
          type: string
          format: uuid
          title: Campaign Id
        policy_set_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Policy Set Id
        violation_rule_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Violation Rule Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        tag_slug:
          type: string
          title: Tag Slug
        country_code:
          type: string
          title: Country Code
        status:
          $ref: '#/components/schemas/AlertStatus'
        closed_by:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Closed By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        scan_url:
          type: string
          title: Scan Url
        offer_url:
          type: string
          title: Offer Url
        tag_display_name:
          type: string
          title: Tag Display Name
        policy_set_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Policy Set Name
        rule_type:
          type: string
          title: Rule Type
          default: tag
        matched_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Matched Value
      type: object
      required:
      - id
      - scan_id
      - campaign_id
      - policy_set_id
      - violation_rule_id
      - organization_id
      - tag_slug
      - country_code
      - status
      - closed_by
      - created_at
      - updated_at
      - scan_url
      - offer_url
      - tag_display_name
      title: AlertResponse
      description: 'Alert returned by API endpoints.


        ``rule_type`` discriminates the underlying violation rule

        (``tag`` / ``iab_v3`` / ``brand`` / ``ai_category`` / ``custom_taxonomy``).

        ``matched_value`` carries the human-readable rendering of what

        actually matched (the IAB breadcrumb, brand string, etc.) — for

        ``tag`` rules the value is the tag slug itself and ``matched_value``

        is therefore ``None``. Together they let API + MCP consumers render

        kind-aware copy without re-deriving from synthetic ``tag_slug``

        keys (e.g. ``custom_taxonomy:sections:Finance > Lending``).


        ``policy_set_name`` is the display name of the policy set that raised

        the alert, denormalized so clients can render it without a second

        lookup. ``None`` when the alert predates policy-set attribution or the

        set has since been deleted.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BulkUpdateAlertStatusRequest:
      properties:
        status:
          $ref: '#/components/schemas/AlertStatus'
        ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Ids
        all_matching:
          type: boolean
          title: All Matching
          default: false
        filter_status:
          anyOf:
          - $ref: '#/components/schemas/AlertStatus'
          - type: 'null'
        filter_campaign_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Filter Campaign Id
        filter_policy_set_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
            minItems: 1
          - type: 'null'
          title: Filter Policy Set Ids
        filter_tag_slugs:
          anyOf:
          - items:
              type: string
            type: array
            minItems: 1
          - type: 'null'
          title: Filter Tag Slugs
        filter_country_codes:
          anyOf:
          - items:
              type: string
            type: array
            minItems: 1
          - type: 'null'
          title: Filter Country Codes
        filter_date_from:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Filter Date From
        filter_date_to:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Filter Date To
        filter_timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Filter Timezone
      type: object
      required:
      - status
      title: BulkUpdateAlertStatusRequest
      description: "Request body for POST /alerts/bulk-status.\n\nExactly one selection mode must be used:\n\n* ``ids`` — an explicit, non-empty list of alert ids (capped at\n  1000 to bound the request).\n* ``all_matching=True`` — every alert matching the ``filter_*``\n  fields (omitting all of them selects the whole org). This is the\n  \"Select all\" path for large inboxes.\n\nThe ``filter_*`` fields mirror the list endpoint's query params\none-for-one. They have to: \"select all matching\" must act on exactly\nthe rows the caller can see in the table, never a wider set.\n\n``status`` is the target; invalid transitions per alert are skipped."
    PaginatedResponse_AlertResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AlertResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - limit
      - pages
      title: PaginatedResponse[AlertResponse]
    BulkUpdateAlertStatusResponse:
      properties:
        updated:
          type: integer
          title: Updated
        skipped:
          type: integer
          title: Skipped
      type: object
      required:
      - updated
      - skipped
      title: BulkUpdateAlertStatusResponse
      description: 'Outcome of a bulk status change.


        ``updated`` is the number of alerts actually transitioned;

        ``skipped`` counts selected alerts that were in a state from which

        the requested transition is not allowed.'
    AlertStatsResponse:
      properties:
        open:
          type: integer
          title: Open
        escalated:
          type: integer
          title: Escalated
        resolved:
          type: integer
          title: Resolved
        dismissed:
          type: integer
          title: Dismissed
      type: object
      required:
      - open
      - escalated
      - resolved
      - dismissed
      title: AlertStatsResponse
      description: Aggregated alert counts by status.
    UpdateAlertStatusRequest:
      properties:
        status:
          $ref: '#/components/schemas/AlertStatus'
      type: object
      required:
      - status
      title: UpdateAlertStatusRequest
      description: 'Request body for PATCH /alerts/{id}/status.


        Pydantic parses ``status`` into AlertStatus at the boundary (422 on invalid).'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer