Kaminari Ad Policy Sets API

openapi: 3.2.0
info:
  title: Kaminari Ad Policy Sets 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: policy-sets
paths:
  /api/v1/policy-sets:
    post:
      tags:
      - policy-sets
      summary: Create Policy Set
      description: Create a policy set.
      operationId: create_policy_set_api_v1_policy_sets_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePolicySetRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicySetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - policy-sets
      summary: List Policy Sets
      description: 'List accessible policy sets for the caller''s organization (paginated).


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

        than silent downgrade.'
      operationId: list_policy_sets_api_v1_policy_sets_get
      security:
      - HTTPBearer: []
      parameters:
      - name: visibility
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/VisibilityType'
          - type: 'null'
          title: Visibility
      - 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_PolicySetListItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}:
    get:
      tags:
      - policy-sets
      summary: Get Policy Set
      description: Get a policy set by ID.
      operationId: get_policy_set_api_v1_policy_sets__policy_set_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicySetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - policy-sets
      summary: Update Policy Set
      description: Update a policy set.
      operationId: update_policy_set_api_v1_policy_sets__policy_set_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePolicySetRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicySetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - policy-sets
      summary: Delete Policy Set
      description: Delete a policy set.
      operationId: delete_policy_set_api_v1_policy_sets__policy_set_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}/campaigns:
    get:
      tags:
      - policy-sets
      summary: List Policy Set Campaigns
      description: 'List campaigns bound to a policy set (paginated).


        ``q`` filters by case-insensitive name substring. The detail response

        embeds only a bounded preview of bound campaigns (``campaigns`` +

        ``campaigns_total``); this endpoint serves the full membership.'
      operationId: list_policy_set_campaigns_api_v1_policy_sets__policy_set_id__campaigns_get
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Q
      - 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_LinkedCampaignResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}/campaigns/attach:
    post:
      tags:
      - policy-sets
      summary: Attach Policy Set Campaigns
      description: 'Bind up to 500 campaigns to a policy set.


        Incremental alternative to the PUT full-replace: existing bindings

        stay intact; campaigns bound to another set are reassigned here.'
      operationId: attach_policy_set_campaigns_api_v1_policy_sets__policy_set_id__campaigns_attach_post
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachCampaignsRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}/campaigns/detach:
    post:
      tags:
      - policy-sets
      summary: Detach Policy Set Campaigns
      description: 'Unbind campaigns from a policy set.


        Pass ``campaign_ids`` (ids bound to other sets are ignored) or

        ``detach_all=true`` to clear the whole membership.'
      operationId: detach_policy_set_campaigns_api_v1_policy_sets__policy_set_id__campaigns_detach_post
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetachCampaignsRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}/set-default:
    post:
      tags:
      - policy-sets
      summary: Set Default Policy Set
      description: 'Mark or clear this set as the organization''s default for new campaigns.


        At most one owned set may be default. ``is_default: true`` replaces any

        previous default; ``false`` leaves the organization without one. A

        missing ``policy_set_id`` on campaign create then uses this set

        (or stays unbound if none is set). Explicit ``null`` on create still

        opts out. Foreign public sets cannot be made default.'
      operationId: set_default_policy_set_api_v1_policy_sets__policy_set_id__set_default_post
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetDefaultPolicySetRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}/request-approval:
    post:
      tags:
      - policy-sets
      summary: Request Public Approval
      description: Request public approval for a policy set.
      operationId: request_public_approval_api_v1_policy_sets__policy_set_id__request_approval_post
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/policy-sets/{policy_set_id}/unpublish:
    post:
      tags:
      - policy-sets
      summary: Unpublish Policy Set
      description: 'Return a policy set to private.


        Inverse of ``request-approval``: takes an approved public set out of

        the shared catalog, or withdraws a publication request that is still

        awaiting moderation. Idempotent on an already-private set.'
      operationId: unpublish_policy_set_api_v1_policy_sets__policy_set_id__unpublish_post
      security:
      - HTTPBearer: []
      parameters:
      - name: policy_set_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Set Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SetDefaultPolicySetRequest:
      properties:
        is_default:
          type: boolean
          title: Is Default
          description: True makes this the organization's default for new campaigns (clearing any previous default). False clears the flag on this set and leaves the organization without a default.
      type: object
      required:
      - is_default
      title: SetDefaultPolicySetRequest
      description: Request body for POST /policy-sets/{id}/set-default.
    IabV3PolicyCategoryRequest:
      properties:
        tier1:
          type: string
          maxLength: 200
          minLength: 1
          title: Tier1
        tier2:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier2
        tier3:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier3
        tier4:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier4
      type: object
      required:
      - tier1
      title: IabV3PolicyCategoryRequest
      description: 'The validated IAB V3 prefix for an ``iab_v3`` rule.


        ``tier1`` is required (the canonical V3 tier1 name); deeper tiers

        are optional and form a prefix at evaluation time. Path validity

        against the canonical V3 tree is enforced by the

        :class:`IabV3TaxonomyReader` in the use case: non-canonical paths

        are rejected before they reach the repository.'
    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
    PaginatedResponse_LinkedCampaignResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/LinkedCampaignResponse'
          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[LinkedCampaignResponse]
    DetachCampaignsRequest:
      properties:
        campaign_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 500
          title: Campaign Ids
        detach_all:
          type: boolean
          title: Detach All
          default: false
      type: object
      title: DetachCampaignsRequest
      description: 'Request body for POST /policy-sets/{id}/campaigns/detach.


        Incremental unbind: listed campaigns bound to this set get their FK

        cleared; ids bound elsewhere are ignored. ``detach_all=true`` clears

        the whole org-scoped membership and ignores ``campaign_ids``.'
    PolicyEntryCustomTaxonomyResponse:
      properties:
        taxonomy_id:
          type: string
          format: uuid
          title: Taxonomy Id
        tier1:
          type: string
          title: Tier1
        tier2:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier2
        tier3:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier3
        tier4:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier4
      type: object
      required:
      - taxonomy_id
      - tier1
      title: PolicyEntryCustomTaxonomyResponse
      description: The custom-taxonomy node prefix on a ``custom_taxonomy`` rule.
    CreatePolicySetRequest:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        description:
          type: string
          maxLength: 2000
          title: Description
          default: ''
        entries:
          items:
            $ref: '#/components/schemas/PolicyEntryRequest'
          type: array
          maxItems: 500
          minItems: 1
          title: Entries
        campaign_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 2000
          title: Campaign Ids
      type: object
      required:
      - name
      - entries
      title: CreatePolicySetRequest
      description: Request body for POST /policy-sets.
    PolicyEntryAiCategoryResponse:
      properties:
        tier1:
          type: string
          title: Tier1
        tier2:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier2
        tier3:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier3
        tier4:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier4
      type: object
      required:
      - tier1
      title: PolicyEntryAiCategoryResponse
      description: The freeform AI-category prefix on an ``ai_category`` rule.
    VisibilityType:
      type: string
      enum:
      - private
      - public
      title: VisibilityType
      description: Controls who can see and use a policy set.
    LinkedCampaignResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        is_archived:
          type: boolean
          title: Is Archived
      type: object
      required:
      - id
      - name
      - is_archived
      title: LinkedCampaignResponse
      description: Campaign bound to a policy set, surfaced on the Policy Set form.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PolicySetResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        visibility:
          type: string
          title: Visibility
        is_approved:
          type: boolean
          title: Is Approved
        is_default:
          type: boolean
          title: Is Default
        entries:
          items:
            $ref: '#/components/schemas/PolicyEntryResponse'
          type: array
          title: Entries
        campaigns:
          items:
            $ref: '#/components/schemas/LinkedCampaignResponse'
          type: array
          title: Campaigns
        campaigns_total:
          type: integer
          title: Campaigns Total
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - description
      - organization_id
      - visibility
      - is_approved
      - is_default
      - entries
      - created_at
      title: PolicySetResponse
      description: 'Policy set returned by API (with entries + bound-campaigns preview).


        ``campaigns`` is a bounded preview (first N by name, N =

        ``PoliciesSettings.campaigns_preview_limit``); ``campaigns_total``

        carries the real membership size. The full list is served by the

        paginated ``GET /policy-sets/{id}/campaigns`` endpoint.'
    AiCategoryRequest:
      properties:
        tier1:
          type: string
          maxLength: 200
          minLength: 1
          title: Tier1
        tier2:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier2
        tier3:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier3
        tier4:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier4
      type: object
      required:
      - tier1
      title: AiCategoryRequest
      description: 'The freeform AI-category prefix carried by an ``ai_category`` rule.


        ``tier1`` is required; deeper tiers tighten the prefix. Unlike

        ``iab_v3`` rules, the API does NOT validate the path against any

        canonical tree — the AI category field on a scan is freeform per

        classification. The only structural rule is "no gaps":

        ``tier3`` requires ``tier2``, ``tier4`` requires ``tier3``.'
    PolicyEntryRequest:
      properties:
        rule_type:
          type: string
          enum:
          - tag
          - iab_v3
          - brand
          - ai_category
          - custom_taxonomy
          title: Rule Type
          default: tag
        tag_slug:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: Tag Slug
        iab_v3:
          anyOf:
          - $ref: '#/components/schemas/IabV3PolicyCategoryRequest'
          - type: 'null'
        brand:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Brand
        ai_category:
          anyOf:
          - $ref: '#/components/schemas/AiCategoryRequest'
          - type: 'null'
        custom_taxonomy:
          anyOf:
          - $ref: '#/components/schemas/CustomTaxonomyRefRequest'
          - type: 'null'
        country_codes:
          items:
            type: string
          type: array
          maxItems: 50
          title: Country Codes
      type: object
      title: PolicyEntryRequest
      description: 'A single entry in a policy set creation/update request.


        Sum type discriminated by :attr:`rule_type`. The validator below

        enforces that exactly the value-block matching ``rule_type`` is

        populated; the API layer additionally checks the IAB V3 prefix

        against the canonical taxonomy and validates ``custom_taxonomy``

        ownership against the caller''s organization.'
    PolicyEntryResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        rule_type:
          type: string
          title: Rule Type
        tag_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Tag Slug
        iab_v3:
          anyOf:
          - $ref: '#/components/schemas/PolicyEntryIabV3Response'
          - type: 'null'
        brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand
        ai_category:
          anyOf:
          - $ref: '#/components/schemas/PolicyEntryAiCategoryResponse'
          - type: 'null'
        custom_taxonomy:
          anyOf:
          - $ref: '#/components/schemas/PolicyEntryCustomTaxonomyResponse'
          - type: 'null'
        country_codes:
          items:
            type: string
          type: array
          title: Country Codes
      type: object
      required:
      - id
      - rule_type
      - country_codes
      title: PolicyEntryResponse
      description: 'A single entry in a policy set response.


        Sum type — exactly one value-block is populated per row depending

        on :attr:`rule_type` (``tag`` / ``iab_v3`` / ``brand`` /

        ``ai_category`` / ``custom_taxonomy``). The other blocks are

        ``null`` and should be ignored by the client.'
    PolicySetListItem:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        visibility:
          type: string
          title: Visibility
        is_approved:
          type: boolean
          title: Is Approved
        is_default:
          type: boolean
          title: Is Default
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - description
      - organization_id
      - visibility
      - is_approved
      - is_default
      - created_at
      title: PolicySetListItem
      description: Policy set in list responses (without entries).
    AttachCampaignsRequest:
      properties:
        campaign_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 500
          minItems: 1
          title: Campaign Ids
      type: object
      required:
      - campaign_ids
      title: AttachCampaignsRequest
      description: 'Request body for POST /policy-sets/{id}/campaigns/attach.


        Incremental bind: the listed campaigns are bound to the set (campaigns

        bound to another set are reassigned); other bindings stay intact.

        Large memberships are built up in <=500-id batches.'
    PaginatedResponse_PolicySetListItem_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PolicySetListItem'
          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[PolicySetListItem]
    UpdatePolicySetRequest:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        description:
          type: string
          maxLength: 2000
          title: Description
          default: ''
        entries:
          items:
            $ref: '#/components/schemas/PolicyEntryRequest'
          type: array
          maxItems: 500
          minItems: 1
          title: Entries
        campaign_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 2000
          title: Campaign Ids
      type: object
      required:
      - name
      - entries
      title: UpdatePolicySetRequest
      description: 'Request body for PUT /policy-sets/{id}.


        ``campaign_ids`` uses full-replace semantics but is only applied when

        present in the payload (``model_fields_set``) so v1 clients that omit

        it never wipe existing bindings.'
    CustomTaxonomyRefRequest:
      properties:
        taxonomy_id:
          type: string
          format: uuid
          title: Taxonomy Id
        tier1:
          type: string
          maxLength: 200
          minLength: 1
          title: Tier1
        tier2:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier2
        tier3:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier3
        tier4:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Tier4
      type: object
      required:
      - taxonomy_id
      - tier1
      title: CustomTaxonomyRefRequest
      description: 'Reference to one node-prefix inside a per-org custom taxonomy.


        ``taxonomy_id`` is checked at use-case time against the caller''s

        org (cross-BC ownership reader); ``tier1`` is required; deeper

        tiers tighten the prefix. Tier values are NOT validated against

        the taxonomy tree at write time — eval-time mismatch simply

        means the rule never fires (safe).'
    PolicyEntryIabV3Response:
      properties:
        tier1:
          type: string
          title: Tier1
        tier2:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier2
        tier3:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier3
        tier4:
          anyOf:
          - type: string
          - type: 'null'
          title: Tier4
      type: object
      required:
      - tier1
      title: PolicyEntryIabV3Response
      description: The validated IAB V3 prefix on an ``iab_v3`` rule.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer