Kaminari Ad Account API

openapi: 3.2.0
info:
  title: Kaminari Ad Account 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: Account
paths:
  /api/v1/account:
    get:
      tags:
      - Account
      summary: Get Org
      description: Return the caller's organization.
      operationId: get_org_api_v1_account_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgResponse'
      security:
      - HTTPBearer: []
    patch:
      tags:
      - Account
      summary: Update Org
      description: Update the caller's organization name.
      operationId: update_org_api_v1_account_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrgRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/account/labels:
    get:
      tags:
      - Account
      summary: List Labels
      description: List custom label definitions for the caller's organization.
      operationId: list_labels_api_v1_account_labels_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/LabelDefinitionResponse'
                type: array
                title: Response List Labels Api V1 Account Labels Get
      security:
      - HTTPBearer: []
    put:
      tags:
      - Account
      summary: Update Labels
      description: Replace all custom label definitions for the organization.
      operationId: update_labels_api_v1_account_labels_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLabelDefinitionsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/LabelDefinitionResponse'
                type: array
                title: Response Update Labels Api V1 Account Labels Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/account/users:
    get:
      tags:
      - Account
      summary: List Org Users
      description: List users in the caller's organization.
      operationId: list_org_users_api_v1_account_users_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserResponse'
                type: array
                title: Response List Org Users Api V1 Account Users Get
      security:
      - HTTPBearer: []
  /api/v1/account/users/invite:
    post:
      tags:
      - Account
      summary: Invite User
      description: Invite a new user to the caller's organization.
      operationId: invite_user_api_v1_account_users_invite_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteUserRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/account/users/{user_id}/role:
    patch:
      tags:
      - Account
      summary: Update User Role
      description: Change a user's role within the organization.
      operationId: update_user_role_api_v1_account_users__user_id__role_patch
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRoleRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/account/users/{user_id}:
    delete:
      tags:
      - Account
      summary: Remove User
      description: Soft-delete a user from the organization.
      operationId: remove_user_api_v1_account_users__user_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/account/users/{user_id}/transfer-ownership:
    post:
      tags:
      - Account
      summary: Transfer Ownership
      description: Transfer organization ownership to another user.
      operationId: transfer_ownership_api_v1_account_users__user_id__transfer_ownership_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/account/api-keys:
    get:
      tags:
      - Account
      summary: List Api Keys
      description: List API keys in the caller's organization.
      operationId: list_api_keys_api_v1_account_api_keys_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ApiKeyResponse'
                type: array
                title: Response List Api Keys Api V1 Account Api Keys Get
      security:
      - HTTPBearer: []
    post:
      tags:
      - Account
      summary: Create Api Key
      description: Create a new API key (full key shown once).
      operationId: create_api_key_api_v1_account_api_keys_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/account/api-keys/{key_id}:
    delete:
      tags:
      - Account
      summary: Revoke Api Key
      description: Revoke (delete) an API key.
      operationId: revoke_api_key_api_v1_account_api_keys__key_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Key Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/account/roles:
    get:
      tags:
      - Account
      summary: List Org Roles
      description: List roles available to the caller's organization.
      operationId: list_org_roles_api_v1_account_roles_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RoleResponse'
                type: array
                title: Response List Org Roles Api V1 Account Roles Get
      security:
      - HTTPBearer: []
    post:
      tags:
      - Account
      summary: Create Custom Role
      description: Create a custom role for the organization.
      operationId: create_custom_role_api_v1_account_roles_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomRoleRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    OrgTransitionOptionResponse:
      properties:
        target_status:
          $ref: '#/components/schemas/OrganizationStatus'
        action:
          $ref: '#/components/schemas/OrgTransitionAction'
      type: object
      required:
      - target_status
      - action
      title: OrgTransitionOptionResponse
      description: 'A status the org may move to, plus the admin action that does it.


        Computed from :class:`OrgStatusTransitionPolicy` and surfaced on the

        admin org detail response so the UI offers exactly the transitions

        the backend allows.'
    OrgTransitionAction:
      type: string
      enum:
      - approve
      - reject
      - suspend
      - reactivate
      title: OrgTransitionAction
      description: 'The admin operation that drives a given org status transition.


        Maps a target :class:`OrganizationStatus` to the endpoint/use case

        that reaches it, so the UI can dispatch the right call without

        re-encoding the transition graph.'
    UpdateOrgRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Name
      type: object
      title: UpdateOrgRequest
      description: 'Request body for organization update.


        ``name`` accepts the same bounds as

        :class:`UpdateOrganizationAdminRequest` so both rename paths (owner

        self-service vs admin override) share a single validation contract:

        1-200 chars, leading/trailing whitespace stripped before persistence.'
    InviteUserRequest:
      properties:
        email:
          type: string
          maxLength: 254
          title: Email
        name:
          type: string
          maxLength: 200
          title: Name
          default: ''
        role_id:
          type: string
          format: uuid
          title: Role Id
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
      additionalProperties: false
      type: object
      required:
      - email
      - role_id
      title: InviteUserRequest
      description: 'Request body for user invitation.


        Legacy IANA timezone aliases are normalised to canonical names by

        :data:`OptionalTimezone` so the invitee row in ``users`` always

        holds a name that ``ZoneInfo`` accepts.'
    UserResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        email:
          type: string
          title: Email
        name:
          type: string
          title: Name
        role_id:
          type: string
          format: uuid
          title: Role Id
        role_name:
          type: string
          title: Role Name
        role_scope:
          type: string
          title: Role Scope
          default: org
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        organization_name:
          type: string
          title: Organization Name
        is_active:
          type: boolean
          title: Is Active
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - email
      - name
      - role_id
      - role_name
      - organization_id
      - organization_name
      - is_active
      - created_at
      title: UserResponse
      description: 'User details returned to clients.


        The ``organization_*`` and ``role_id`` fields are additive

        (introduced in COOP-14061 follow-up) — older clients ignore

        them while admin SPA (and self-service "team members" pages)

        need them for filtering, linking, and editing.


        ``role_scope`` ("org" / "admin") is additive too (COOP-14131): the

        admin SPA inspects it to (a) hide admin-scope rows from the regular

        Edit-User role dropdown and (b) render a read-only Internal Admin

        badge in place of editable controls when the user is staff. Older

        clients that ignore it keep working.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LabelDefinitionItem:
      properties:
        key:
          type: string
          maxLength: 50
          title: Key
        display_name:
          type: string
          maxLength: 100
          title: Display Name
        auto_extract:
          type: boolean
          title: Auto Extract
          default: false
        show_in_public_report:
          type: boolean
          title: Show In Public Report
          description: Show this label's value on the unauthenticated shared scan report. The PUT replaces the whole list, so omitting it hides the label.
          default: false
      type: object
      required:
      - key
      - display_name
      title: LabelDefinitionItem
      description: A single label definition within the update request.
    ApiKeyResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        key_prefix:
          type: string
          title: Key Prefix
        name:
          type: string
          title: Name
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - key_prefix
      - name
      - expires_at
      - created_at
      title: ApiKeyResponse
      description: API key metadata (full key is never shown after creation).
    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
    LabelDefinitionResponse:
      properties:
        key:
          type: string
          title: Key
        display_name:
          type: string
          title: Display Name
        position:
          type: integer
          title: Position
        auto_extract:
          type: boolean
          title: Auto Extract
        show_in_public_report:
          type: boolean
          title: Show In Public Report
      type: object
      required:
      - key
      - display_name
      - position
      - auto_extract
      - show_in_public_report
      title: LabelDefinitionResponse
      description: Label definition info returned to clients.
    RoleResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        scope:
          type: string
          title: Scope
        is_system:
          type: boolean
          title: Is System
        permissions:
          items:
            type: string
          type: array
          title: Permissions
      type: object
      required:
      - id
      - name
      - scope
      - is_system
      - permissions
      title: RoleResponse
      description: Role details with associated permission codenames.
    CreateApiKeyRequest:
      properties:
        name:
          type: string
          title: Name
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
      type: object
      required:
      - name
      title: CreateApiKeyRequest
      description: Request body for API key creation.
    OrganizationStatus:
      type: string
      enum:
      - pending_email_verification
      - pending_admin_approval
      - active
      - suspended
      - rejected
      title: OrganizationStatus
      description: "Lifecycle state of an :class:`Organization`.\n\n* ``PENDING_EMAIL_VERIFICATION`` — self-service signup, owner has\n  not clicked the verification link yet.\n* ``PENDING_ADMIN_APPROVAL`` — email verified, awaiting admin\n  approval (gated by ``signup_admin_approval_required`` flag).\n* ``ACTIVE`` — fully usable; users can log in, scans run, billing\n  meters tick.\n* ``SUSPENDED`` — admin froze the org (formerly ``is_active=False``).\n* ``REJECTED`` — admin denied a self-service signup; soft-delete\n  for audit trail. Recoverable: an admin can approve it in place\n  (REJECTED → ACTIVE via ``AdminApproveOrganization``) or unblock\n  it to free the email for a fresh signup (deletes the owner)."
    ApiKeyCreatedResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        key_prefix:
          type: string
          title: Key Prefix
        full_key:
          type: string
          title: Full Key
        name:
          type: string
          title: Name
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - key_prefix
      - full_key
      - name
      - expires_at
      - created_at
      title: ApiKeyCreatedResponse
      description: One-time response with the full API key visible.
    UpdateUserRoleRequest:
      properties:
        role_id:
          type: string
          format: uuid
          title: Role Id
      type: object
      required:
      - role_id
      title: UpdateUserRoleRequest
      description: Request body for user role update.
    UpdateLabelDefinitionsRequest:
      properties:
        labels:
          items:
            $ref: '#/components/schemas/LabelDefinitionItem'
          type: array
          title: Labels
      type: object
      required:
      - labels
      title: UpdateLabelDefinitionsRequest
      description: Request body to replace all label definitions for an organization.
    OrgResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        owner_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Owner Id
        status:
          $ref: '#/components/schemas/OrganizationStatus'
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
        created_at:
          type: string
          format: date-time
          title: Created At
        available_transitions:
          items:
            $ref: '#/components/schemas/OrgTransitionOptionResponse'
          type: array
          title: Available Transitions
          default: []
        is_active:
          type: boolean
          title: Is Active
          description: 'Backward-compat: True iff status == ACTIVE.'
          readOnly: true
      type: object
      required:
      - id
      - name
      - owner_id
      - status
      - created_at
      - is_active
      title: OrgResponse
      description: 'Organization details returned to clients.


        ``status`` is the canonical lifecycle field (Phase 0 of COOP-14061).

        ``is_active`` remains as a computed backward-compat field — UI

        clients still reading the old boolean stay green for one release;

        drop it after every consumer has migrated to ``status``.


        ``owner_id`` is ``None`` for ownerless orgs — the Kadam system org

        (seeded NULL) and any org whose owner was transferred out.'
    CreateCustomRoleRequest:
      properties:
        name:
          type: string
          title: Name
        permissions:
          items:
            type: string
          type: array
          title: Permissions
      type: object
      required:
      - name
      - permissions
      title: CreateCustomRoleRequest
      description: Request body for custom role creation.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer