Kaminari Ad Runs API

openapi: 3.2.0
info:
  title: Kaminari Ad Runs 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: Runs
paths:
  /api/v1/runs/{run_id}:
    get:
      tags:
      - Runs
      summary: Get Run
      description: Get run detail with progress counters.
      operationId: get_run_api_v1_runs__run_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/runs/{run_id}/cancel:
    post:
      tags:
      - Runs
      summary: Cancel Run
      description: Cancel all pending scans for a run.
      operationId: cancel_run_api_v1_runs__run_id__cancel_post
      security:
      - HTTPBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelPendingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/runs/{run_id}/scans:
    get:
      tags:
      - Runs
      summary: List Run Scans
      description: 'List scan tiles for a run (paginated).


        ``limit`` is capped at 200. Iterate via ``page``/``limit`` using

        the returned ``total``/``pages`` fields.'
      operationId: list_run_scans_api_v1_runs__run_id__scans_get
      security:
      - HTTPBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - 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_ScanTileResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PaginatedResponse_ScanTileResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ScanTileResponse'
          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[ScanTileResponse]
    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
    RunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        campaign_id:
          type: string
          format: uuid
          title: Campaign Id
        label:
          type: string
          title: Label
        total:
          type: integer
          title: Total
        completed:
          type: integer
          title: Completed
        failed:
          type: integer
          title: Failed
        partial:
          type: integer
          title: Partial
        cancelled:
          type: integer
          title: Cancelled
        source:
          $ref: '#/components/schemas/RunSource'
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - campaign_id
      - label
      - total
      - completed
      - failed
      - partial
      - cancelled
      - source
      - created_at
      title: RunResponse
      description: Run info with progress counters.
    RunSource:
      type: string
      enum:
      - ui
      - api
      title: RunSource
      description: 'Where the run was initiated from.


        ``UI`` — explicit ``POST /campaigns/{id}/run`` from the dashboard.

        ``API`` — auto-created bucket for ``POST /api/v1/scans`` requests that

        carry a ``campaign_id`` but no ``run_id``. One API run per

        (campaign, organization, UTC-day).'
    ScanTileResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        country_code:
          type: string
          title: Country Code
        status:
          type: string
          title: Status
        offer_url:
          type: string
          title: Offer Url
          default: ''
        screenshot_url:
          type: string
          title: Screenshot Url
          description: Page screenshot at ?w=400 — a top-cropped tile of the capture, not the whole page. Fetch the endpoint without ?w= for the full frame.
          default: ''
        report_url:
          type: string
          title: Report Url
          default: ''
        public_report_url:
          type: string
          title: Public Report Url
          default: ''
        elapsed_ms:
          type: integer
          title: Elapsed Ms
          default: 0
        error:
          type: string
          title: Error
          default: ''
      type: object
      required:
      - id
      - country_code
      - status
      title: ScanTileResponse
      description: Lightweight scan data for tile grid display.
    CancelPendingResponse:
      properties:
        cancelled_count:
          type: integer
          title: Cancelled Count
      type: object
      required:
      - cancelled_count
      title: CancelPendingResponse
      description: Number of scans moved from pending to cancelled.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer