Kaminari Ad Custom Rules API

openapi: 3.2.0
info:
  title: Kaminari Ad Custom Rules 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: custom-rules
paths:
  /api/v1/custom-rules:
    post:
      tags:
      - custom-rules
      summary: Create Custom Rule
      description: Create a custom tag rule.
      operationId: create_custom_rule_api_v1_custom_rules_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomRuleRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRuleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - custom-rules
      summary: List Custom Rules
      description: 'List custom rules for the caller''s organization (paginated).


        ``limit`` is capped at 200 — iterate via ``page`` + ``limit`` and

        the returned ``total`` / ``pages``.'
      operationId: list_custom_rules_api_v1_custom_rules_get
      security:
      - HTTPBearer: []
      parameters:
      - 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_CustomRuleResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-rules/{rule_id}:
    get:
      tags:
      - custom-rules
      summary: Get Custom Rule
      description: Get a custom tag rule by ID.
      operationId: get_custom_rule_api_v1_custom_rules__rule_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Rule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRuleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - custom-rules
      summary: Update Custom Rule
      description: Update a custom tag rule.
      operationId: update_custom_rule_api_v1_custom_rules__rule_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Rule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomRuleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRuleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - custom-rules
      summary: Delete Custom Rule
      description: Delete a custom tag rule.
      operationId: delete_custom_rule_api_v1_custom_rules__rule_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Rule Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-rules/test:
    post:
      tags:
      - custom-rules
      summary: Run Rule Test
      description: Test a rule against an existing scan (real execution via checkers).
      operationId: run_rule_test_api_v1_custom_rules_test_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleTestRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleTestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/custom-rules/test-batch:
    post:
      tags:
      - custom-rules
      summary: Run Rule Test Batch
      description: 'Test up to 20 unsaved rules against up to 50 stored scans in one call.


        The reply always arrives within the request deadline. A cell the

        deadline cut off carries ``error_code=deadline_exceeded``; send just

        those again. A bad rule rejects the request with 422. A missing scan

        or a failed evaluation is reported on its cell; the rest of the matrix

        still returns. One batch per organization runs at a time: a second

        one gets 429 ``checking.rule_test_batch_in_progress``.'
      operationId: run_rule_test_batch_api_v1_custom_rules_test_batch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleTestBatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleTestBatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    RuleTestBatchCell:
      properties:
        index:
          type: integer
          title: Index
        rule_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Rule Id
        scan_id:
          type: string
          format: uuid
          title: Scan Id
        matched:
          type: boolean
          title: Matched
        tags:
          items:
            $ref: '#/components/schemas/RuleTestTagResult'
          type: array
          title: Tags
        elapsed_ms:
          type: integer
          title: Elapsed Ms
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
      type: object
      required:
      - index
      - scan_id
      - matched
      - tags
      - elapsed_ms
      title: RuleTestBatchCell
      description: 'One rule applied to one scan.


        ``index`` is the rule''s position in the request ``rules`` array, so it

        repeats once per scan. ``rule_id`` echoes the optional client id. When

        the pair could not be evaluated, ``error`` says why in words and

        ``error_code`` in a stable value: ``timed_out``, ``deadline_exceeded``,

        ``failed``, ``invalid_rule``, ``llm_failed``, ``content_prohibited`` or

        ``scan_not_found``. Other cells of the batch still return.

        ``deadline_exceeded`` means the batch ran out of time before this

        cell; sending it again in a smaller batch may succeed.'
    TagVisibility:
      type: string
      enum:
      - hidden
      - internal
      - public
      title: TagVisibility
      description: Visibility tier for a tag definition.
    RuleTestBatchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/RuleTestBatchCell'
          type: array
          title: Results
        summary:
          $ref: '#/components/schemas/RuleTestBatchSummary'
      type: object
      required:
      - results
      - summary
      title: RuleTestBatchResponse
      description: Response from POST /api/v1/custom-rules/test-batch.
    RuleTestRequest:
      properties:
        scan_id:
          type: string
          format: uuid
          title: Scan Id
        rule_type:
          type: string
          title: Rule Type
        config:
          additionalProperties: true
          type: object
          title: Config
        target:
          type: string
          title: Target
          default: page
        name:
          type: string
          title: Name
          default: Test Rule
        context:
          type: string
          enum:
          - isolated
          - production
          title: Context
          default: isolated
        rule_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Rule Id
      type: object
      required:
      - scan_id
      - rule_type
      - config
      title: RuleTestRequest
      description: "Request body for POST /custom-rules/test.\n\n``context`` selects the prompt mode for LLM rules:\n\n* ``isolated`` (default) — the prompt carries only the draft rule;\n  good for iterating on criteria wording.\n* ``production`` — the prompt carries the org's full active rule\n  set with the draft substituted for its saved version\n  (``rule_id``), exactly like a real scan; the reply is filtered\n  to the draft's tags. Only valid for ``rule_type=\"llm\"``."
    RuleTestBatchRequest:
      properties:
        rules:
          items:
            $ref: '#/components/schemas/RuleTestBatchRule'
          type: array
          maxItems: 20
          minItems: 1
          title: Rules
        scan_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 50
          minItems: 1
          title: Scan Ids
      type: object
      required:
      - rules
      - scan_ids
      title: RuleTestBatchRequest
      description: 'Body for POST /api/v1/custom-rules/test-batch.


        Up to 20 rules against up to 50 stored scans. A request over either

        cap, or with any invalid rule, is rejected before a scan is loaded.'
    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
    RuleTestBatchRule:
      properties:
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        rule_type:
          type: string
          title: Rule Type
        config:
          additionalProperties: true
          type: object
          title: Config
        target:
          type: string
          title: Target
          default: page
        name:
          type: string
          title: Name
          default: Test Rule
      type: object
      required:
      - rule_type
      - config
      title: RuleTestBatchRule
      description: 'One rule to evaluate. ``id`` is echoed back; it is not looked up.


        ``name`` is the label the LLM prompt quotes, the same field the

        single test sends as ``body.name``. The default matches that test,

        so an omitted name does not change the prompt.'
    CustomRuleResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
        name:
          type: string
          title: Name
        tag_slug:
          type: string
          title: Tag Slug
        rule_type:
          type: string
          title: Rule Type
        config:
          additionalProperties: true
          type: object
          title: Config
        target:
          type: string
          title: Target
        is_active:
          type: boolean
          title: Is Active
        created_at:
          type: string
          format: date-time
          title: Created At
        scope:
          type: string
          title: Scope
          default: personal
        tag_visibility:
          additionalProperties:
            type: string
          type: object
          title: Tag Visibility
      type: object
      required:
      - id
      - organization_id
      - name
      - tag_slug
      - rule_type
      - config
      - target
      - is_active
      - created_at
      title: CustomRuleResponse
      description: Custom tag rule returned by API.
    UpdateCustomRuleRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        tag_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Tag Slug
        config:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Config
        target:
          anyOf:
          - type: string
          - type: 'null'
          title: Target
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
        tag_visibility:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/TagVisibility'
            type: object
            maxProperties: 50
          - type: 'null'
          title: Tag Visibility
      type: object
      title: UpdateCustomRuleRequest
      description: Request body for PUT /custom-rules/{id}. All fields optional.
    RuleTestBatchSummary:
      properties:
        total:
          type: integer
          title: Total
        matched:
          type: integer
          title: Matched
        failed:
          type: integer
          title: Failed
        deadline_exceeded:
          type: integer
          title: Deadline Exceeded
      type: object
      required:
      - total
      - matched
      - failed
      - deadline_exceeded
      title: RuleTestBatchSummary
      description: 'Counts over the flat cell list.


        ``matched`` counts cells that matched and have no ``error``.

        ``failed`` counts cells whose ``error`` is set; ``deadline_exceeded``

        is the part of them the batch deadline cut off.'
    PaginatedResponse_CustomRuleResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CustomRuleResponse'
          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[CustomRuleResponse]
    RuleTestResponse:
      properties:
        matched:
          type: boolean
          title: Matched
        tags:
          items:
            $ref: '#/components/schemas/RuleTestTagResult'
          type: array
          title: Tags
        elapsed_ms:
          type: integer
          title: Elapsed Ms
        llm_failed:
          type: boolean
          title: Llm Failed
          default: false
        llm_call_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Llm Call Id
        llm_prompt_url:
          type: string
          title: Llm Prompt Url
          default: ''
        llm_response_url:
          type: string
          title: Llm Response Url
          default: ''
      type: object
      required:
      - matched
      - tags
      - elapsed_ms
      title: RuleTestResponse
      description: 'Response from POST /custom-rules/test.


        ``llm_failed`` is True when the LLM provider could not complete the

        evaluation (API error, invalid response). The UI surfaces this as a

        warning instead of showing a misleading "No match".


        ``llm_call_id`` / ``llm_prompt_url`` / ``llm_response_url`` are

        populated only when an LLM-based rule actually ran and the worker

        persisted the call''s telemetry. The UI renders collapsible prompt

        and response sections from the two same-origin URLs (served by

        ``/api/internal/llm/calls/{id}/...``); non-LLM rule types and

        runs where telemetry didn''t land leave them empty/None so the

        sections stay hidden.'
    RuleTestTagResult:
      properties:
        tag_slug:
          type: string
          title: Tag Slug
        detail:
          type: string
          title: Detail
          default: ''
      type: object
      required:
      - tag_slug
      title: RuleTestTagResult
      description: A single tag detection from the test.
    CreateCustomRuleRequest:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        tag_slug:
          type: string
          maxLength: 100
          title: Tag Slug
          default: ''
        rule_type:
          type: string
          maxLength: 50
          title: Rule Type
        config:
          additionalProperties: true
          type: object
          maxProperties: 50
          title: Config
        target:
          type: string
          maxLength: 30
          title: Target
          default: page
        tag_visibility:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/TagVisibility'
            type: object
            maxProperties: 50
          - type: 'null'
          title: Tag Visibility
      type: object
      required:
      - name
      - rule_type
      - config
      title: CreateCustomRuleRequest
      description: Request body for POST /custom-rules.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer