openapi: 3.2.0
info:
  title: Karma.Domains Public Webhooks API
  description: 'Public API for Karma.Domains: programmatic access to domain intelligence — reports across auctions, expired, backorder, and buy-now inventories, SEO and authority metrics, Wayback history, availability checks, and Karma Metric.'
  contact:
    name: Karma.Domains
    url: https://karma.domains/
    email: hello@karma.domains
  version: 1.0.0
  x-guidance: 'Paid routes use x402 agent credits. If a request returns HTTP 402, read PAYMENT-REQUIRED and retry the same URL with PAYMENT-SIGNATURE. Optional X-Karma-Plan-Id selects a concrete credit pack. Saved filters: GET/POST /v1/user/saved-filters and GET/PATCH/DELETE /v1/user/saved-filters/{id}. Webhooks: POST /v1/webhooks with an HTTPS URL from Zapier, Make, n8n, or IFTTT. SEO enrich: POST .../enrich-seo then poll GET /v1/reports/enrich-jobs/{job_id}.'
servers:
- url: https://api.karma.domains
  description: Public API (canonical)
- url: https://karma.domains
  description: OpenAPI mirror (same spec)
tags:
- name: Webhooks
paths:
  /v1/webhooks/:
    get:
      tags:
      - Webhooks
      summary: List Webhooks
      description: List webhook subscriptions for the current account.
      operationId: list_webhooks_v1_webhooks__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WebhookSubscriptionResponse'
                type: array
                title: Response List Webhooks V1 Webhooks  Get
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    items:
                      type: object
                    type: array
                    description: x402 v2 payment options (packs × networks)
                  extensions:
                    properties:
                      karma:
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            items:
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                              type: object
                            type: array
                          costs:
                            additionalProperties:
                              type: integer
                            type: object
                        type: object
                      bazaar:
                        type: object
                    type: object
                type: object
      security:
      - Bearer: []
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
    post:
      tags:
      - Webhooks
      summary: Create Webhook
      description: 'Create a webhook subscription. The signing secret is returned once.


        `kind=filter` sends `domain.matched_filter` when a report starts matching

        the same filters as `POST /v1/reports/search`. `kind=reports` watches

        specific reports for auction changes and for this account''s note, tag, and

        favorite changes. `kind=user` sends `usertask.created` and

        `usertask.completed` and does not take a report list.

        Zapier, Make, n8n, and IFTTT use the HTTPS URL from their webhook trigger.'
      operationId: create_webhook_v1_webhooks__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResponse'
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    items:
                      type: object
                    type: array
                    description: x402 v2 payment options (packs × networks)
                  extensions:
                    properties:
                      karma:
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            items:
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                              type: object
                            type: array
                          costs:
                            additionalProperties:
                              type: integer
                            type: object
                        type: object
                      bazaar:
                        type: object
                    type: object
                type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - Bearer: []
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
  /v1/webhooks/{subscription_id}:
    get:
      tags:
      - Webhooks
      summary: Get Webhook
      description: Get one webhook subscription. The signing secret is not included.
      operationId: get_webhook_v1_webhooks__subscription_id__get
      security:
      - Bearer: []
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          title: Subscription Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResponse'
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    type: array
                    description: x402 v2 payment options (packs × networks)
                    items:
                      type: object
                  extensions:
                    type: object
                    properties:
                      karma:
                        type: object
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            type: array
                            items:
                              type: object
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                          costs:
                            type: object
                            additionalProperties:
                              type: integer
                      bazaar:
                        type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
    patch:
      tags:
      - Webhooks
      summary: Patch Webhook
      description: Update a webhook subscription. `status` accepts `active` or `paused`.
      operationId: patch_webhook_v1_webhooks__subscription_id__patch
      security:
      - Bearer: []
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          title: Subscription Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResponse'
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    type: array
                    description: x402 v2 payment options (packs × networks)
                    items:
                      type: object
                  extensions:
                    type: object
                    properties:
                      karma:
                        type: object
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            type: array
                            items:
                              type: object
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                          costs:
                            type: object
                            additionalProperties:
                              type: integer
                      bazaar:
                        type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook
      description: Delete a webhook subscription and stop deliveries.
      operationId: delete_webhook_v1_webhooks__subscription_id__delete
      security:
      - Bearer: []
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          title: Subscription Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MassageResponseSchema'
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    type: array
                    description: x402 v2 payment options (packs × networks)
                    items:
                      type: object
                  extensions:
                    type: object
                    properties:
                      karma:
                        type: object
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            type: array
                            items:
                              type: object
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                          costs:
                            type: object
                            additionalProperties:
                              type: integer
                      bazaar:
                        type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
  /v1/webhooks/{subscription_id}/secret:
    post:
      tags:
      - Webhooks
      summary: Rotate Webhook Secret
      description: Rotate the signing secret. The new secret is returned once.
      operationId: rotate_webhook_secret_v1_webhooks__subscription_id__secret_post
      security:
      - Bearer: []
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          title: Subscription Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResponse'
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    type: array
                    description: x402 v2 payment options (packs × networks)
                    items:
                      type: object
                  extensions:
                    type: object
                    properties:
                      karma:
                        type: object
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            type: array
                            items:
                              type: object
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                          costs:
                            type: object
                            additionalProperties:
                              type: integer
                      bazaar:
                        type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
  /v1/webhooks/{subscription_id}/ping:
    post:
      tags:
      - Webhooks
      summary: Ping Webhook
      description: Send a `webhook.ping` event to the subscription URL and return the attempt.
      operationId: ping_webhook_v1_webhooks__subscription_id__ping_post
      security:
      - Bearer: []
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          title: Subscription Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeliveryResponse'
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    type: array
                    description: x402 v2 payment options (packs × networks)
                    items:
                      type: object
                  extensions:
                    type: object
                    properties:
                      karma:
                        type: object
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            type: array
                            items:
                              type: object
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                          costs:
                            type: object
                            additionalProperties:
                              type: integer
                      bazaar:
                        type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
  /v1/webhooks/{subscription_id}/deliveries:
    get:
      tags:
      - Webhooks
      summary: Webhook Deliveries
      description: Recent delivery attempts for a subscription. Secrets are not included.
      operationId: webhook_deliveries_v1_webhooks__subscription_id__deliveries_get
      security:
      - Bearer: []
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          title: Subscription Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookDeliveryResponse'
                title: Response Webhook Deliveries V1 Webhooks  Subscription Id  Deliveries Get
        '402':
          description: Payment required — x402 agent credits. Read PAYMENT-REQUIRED header (base64 JSON) and retry same URL with PAYMENT-SIGNATURE and optional X-Karma-Plan-Id.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 PaymentRequired JSON
              schema:
                type: string
            X-Karma-Api-Key:
              description: Issued api_key on first successful purchase
              schema:
                type: string
            Link:
              description: Agent skill documentation
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: payment_required
                  accepts:
                    type: array
                    description: x402 v2 payment options (packs × networks)
                    items:
                      type: object
                  extensions:
                    type: object
                    properties:
                      karma:
                        type: object
                        properties:
                          reason:
                            type: string
                            enum:
                            - first_purchase
                            - top_up
                          retry_same_url:
                            type: boolean
                          plan_id_header:
                            type: string
                          recommended_plan_id:
                            type: string
                          keep_api_key:
                            type: boolean
                          packs:
                            type: array
                            items:
                              type: object
                              properties:
                                plan_id:
                                  type: string
                                credits:
                                  type: integer
                                price_usdc:
                                  type: string
                          costs:
                            type: object
                            additionalProperties:
                              type: integer
                      bazaar:
                        type: object
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.50'
          max: '20.00'
        protocols:
        - x402: {}
components:
  schemas:
    WebhookSubscriptionPatch:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        events:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Events
        filter:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Filter
        bases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Bases
        max_events_per_run:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Events Per Run
        ending_soon_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ending Soon Seconds
        reports:
          anyOf:
          - items:
              $ref: '#/components/schemas/WebhookReportRef'
            type: array
          - type: 'null'
          title: Reports
      type: object
      title: WebhookSubscriptionPatch
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WebhookDeliveryResponse:
      properties:
        id:
          type: string
          title: Id
        event_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Id
        event_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Type
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        attempts:
          anyOf:
          - type: integer
          - type: 'null'
          title: Attempts
        last_status_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Status Code
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
        next_attempt_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Attempt At
        created_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Created At
        payload:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Payload
      type: object
      required:
      - id
      title: WebhookDeliveryResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WebhookSubscriptionResponse:
      properties:
        id:
          type: string
          title: Id
        kind:
          type: string
          title: Kind
        url:
          type: string
          title: Url
        status:
          type: string
          title: Status
        events:
          items:
            type: string
          type: array
          title: Events
        filter:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Filter
        bases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Bases
        max_events_per_run:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Events Per Run
        ending_soon_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ending Soon Seconds
        reports:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Reports
        created_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Updated At
        disabled_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Disabled Reason
        cursor_changed_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cursor Changed At
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
      type: object
      required:
      - id
      - kind
      - url
      - status
      - events
      title: WebhookSubscriptionResponse
    WebhookReportRef:
      properties:
        report_type:
          type: string
          title: Report Type
        report_id:
          type: string
          title: Report Id
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
      type: object
      required:
      - report_type
      - report_id
      title: WebhookReportRef
    MassageResponseSchema:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
      type: object
      required:
      - status
      - message
      title: MassageResponseSchema
      description: Massage response schema
    WebhookSubscriptionBody:
      properties:
        kind:
          type: string
          title: Kind
        url:
          type: string
          title: Url
        events:
          items:
            type: string
          type: array
          title: Events
        filter:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Filter
        bases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Bases
        max_events_per_run:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Events Per Run
        ending_soon_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ending Soon Seconds
        reports:
          anyOf:
          - items:
              $ref: '#/components/schemas/WebhookReportRef'
            type: array
          - type: 'null'
          title: Reports
      type: object
      required:
      - kind
      - url
      - events
      title: WebhookSubscriptionBody
  securitySchemes:
    Bearer:
      type: http
      description: API key as Bearer token, or x402 PAYMENT-SIGNATURE for agent credits
      scheme: bearer