Kaminari Ad Proxy API

openapi: 3.2.0
info:
  title: Kaminari Ad Proxy 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: Proxy
paths:
  /api/v1/proxy/targeting:
    get:
      tags:
      - Proxy
      summary: Get Proxy Targeting
      description: 'Return the values accepted in a scan''s `proxy` block for one country.


        Every value listed here is accepted by `POST /api/v1/scans`, in any

        case. That guarantee is about validation only: the provider''s pool

        moves continuously, so a scan may still fail to find an exit node at

        crawl time.


        An unsupported or unknown country returns 200 with empty arrays

        rather than 404 — the useful answer to "can I target here" is a list,

        possibly an empty one.'
      operationId: get_proxy_targeting_api_v1_proxy_targeting_get
      security:
      - HTTPBearer: []
      parameters:
      - name: country_code
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code. Case-insensitive.
          title: Country Code
        description: ISO 3166-1 alpha-2 country code. Case-insensitive.
      - name: proxy_type
        in: query
        required: false
        schema:
          enum:
          - residential
          - mobile
          type: string
          description: 'Which network to describe. Required in practice: the residential and mobile catalogues differ substantially, so values taken from one may be rejected for the other.'
          default: residential
          title: Proxy Type
        description: 'Which network to describe. Required in practice: the residential and mobile catalogues differ substantially, so values taken from one may be rejected for the other.'
      - name: region
        in: query
        required: false
        schema:
          type: string
          description: Narrow `cities` to one region. Omit for the country-wide city list. Pass a value from this endpoint's own `regions` array.
          default: ''
          title: Region
        description: Narrow `cities` to one region. Omit for the country-wide city list. Pass a value from this endpoint's own `regions` array.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyTargetingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ProxyTargetingResponse:
      properties:
        country_code:
          type: string
          title: Country Code
          description: ISO 3166-1 alpha-2 code, upper-case.
        proxy_type:
          type: string
          title: Proxy Type
          description: Network these values belong to. The catalogues differ substantially between residential and mobile, so a value listed for one is not necessarily accepted for the other.
        regions:
          items:
            type: string
          type: array
          title: Regions
          description: Accepted values for `proxy.region`, ordered by pool size (largest first).
        cities:
          items:
            type: string
          type: array
          title: Cities
          description: Accepted values for `proxy.city`, ordered by pool size. Narrowed to the `region` query parameter when one is given; otherwise the country-wide list, which is what to pick from when targeting by country alone. Pairing a region with a city from a different region yields no exit node.
        isps:
          items:
            type: string
          type: array
          title: Isps
          description: Accepted values for `proxy.isp`, ordered by pool size. Mobile carriers when `proxy_type=mobile`.
        refreshed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Refreshed At
          description: When these lists were last verified against the upstream provider, or null if we have not synced this country yet. Null means 'not looked yet', which is different from empty lists with a timestamp, which means 'no targeting available here'. This moves on every sync whether or not the contents changed — use the ETag header to detect actual changes.
        ttl_seconds:
          type: integer
          title: Ttl Seconds
          description: How long these lists may be cached before we re-verify them upstream. Send the ETag back as If-None-Match to revalidate cheaply.
      type: object
      required:
      - country_code
      - proxy_type
      - regions
      - cities
      - isps
      - refreshed_at
      - ttl_seconds
      title: ProxyTargetingResponse
      description: Values accepted in a scan's ``proxy`` block for one country.
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer