openapi: 3.2.0
info:
  title: Karma.Domains Public User 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: User
paths:
  /v1/user/saved-filters:
    get:
      tags:
      - User
      summary: List User Saved Filters
      description: List the user's saved search filters.
      operationId: list_user_saved_filters_v1_user_saved_filters_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserFiltersSchema'
                type: array
                title: Response List User Saved Filters V1 User Saved Filters 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:
      - User
      summary: Create User Saved Filter
      description: 'Create a saved search filter. Agent accounts: 1 credit per call.'
      operationId: create_user_saved_filter_v1_user_saved_filters_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserFilterCreateSchema'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFiltersSchema'
        '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/user/saved-filters/{filter_id}:
    get:
      tags:
      - User
      summary: Get User Saved Filter
      description: Get one saved search filter by id.
      operationId: get_user_saved_filter_v1_user_saved_filters__filter_id__get
      security:
      - Bearer: []
      parameters:
      - name: filter_id
        in: path
        required: true
        schema:
          type: string
          title: Filter Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFiltersSchema'
        '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:
      - User
      summary: Patch User Saved Filter
      description: 'Update one saved search filter. Agent accounts: 1 credit per call.'
      operationId: patch_user_saved_filter_v1_user_saved_filters__filter_id__patch
      security:
      - Bearer: []
      parameters:
      - name: filter_id
        in: path
        required: true
        schema:
          type: string
          title: Filter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserFilterPatchSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFiltersSchema'
        '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:
      - User
      summary: Delete User Saved Filter
      description: 'Delete one saved search filter. Agent accounts: 1 credit per call.'
      operationId: delete_user_saved_filter_v1_user_saved_filters__filter_id__delete
      security:
      - Bearer: []
      parameters:
      - name: filter_id
        in: path
        required: true
        schema:
          type: string
          title: Filter Id
      responses:
        '204':
          description: Successful Response
        '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/user:
    get:
      tags:
      - User
      summary: Get Current User Profile
      description: 'Return the authenticated user''s profile (email, joined date, credits, plans).


        Omits payment stats, UTM, API key, and other internal fields.

        Requires Pro API key (60 req/min). Not cached — balance may change.'
      operationId: get_current_user_profile_v1_user_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserProfileSchema'
        '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: {}
components:
  schemas:
    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
    UserFilterPatchSchema:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        filter:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Filter
        bases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Bases
      type: object
      title: UserFilterPatchSchema
      description: Partial update of a saved search filter.
    UserFiltersSchema:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        filter:
          additionalProperties: true
          type: object
          title: Filter
        bases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Bases
      type: object
      required:
      - id
      - name
      - filter
      title: UserFiltersSchema
      description: User filters schema
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UserFilterCreateSchema:
      properties:
        name:
          type: string
          title: Name
        filter:
          additionalProperties: true
          type: object
          title: Filter
        bases:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Bases
      type: object
      required:
      - name
      - filter
      title: UserFilterCreateSchema
      description: Create a saved search filter. The server assigns id.
    PublicUserProfileSchema:
      properties:
        id:
          type: string
          title: Id
        email:
          type: string
          format: email
          title: Email
        joined:
          type: integer
          title: Joined
          default: 0
        balance:
          type: integer
          title: Balance
          description: Total spendable credits (Pro + Unlimited plan pools + purchased)
          default: 0
        pro_task_credits:
          type: integer
          title: Pro Task Credits
          default: 0
        unlimited_plan:
          type: integer
          title: Unlimited Plan
          default: 0
        pro_plan:
          type: integer
          title: Pro Plan
          default: 0
        unlimited_subscription_info:
          anyOf:
          - $ref: '#/components/schemas/PublicSubscriptionInfoSchema'
          - type: 'null'
        pro_subscription_info:
          anyOf:
          - $ref: '#/components/schemas/PublicSubscriptionInfoSchema'
          - type: 'null'
        lang:
          type: string
          title: Lang
          default: en
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
        home:
          type: string
          title: Home
          default: auctions
        theme:
          type: string
          title: Theme
          default: system
        referral_counter:
          type: integer
          title: Referral Counter
          default: 0
        news:
          anyOf:
          - items:
              $ref: '#/components/schemas/UserNews'
            type: array
          - type: 'null'
          title: News
      type: object
      required:
      - id
      - email
      title: PublicUserProfileSchema
      description: Current user profile for Public API (sanitized subset of UserInfo).
    UserNews:
      properties:
        type:
          type: string
          pattern: ^(info|warning|success|error)$
          title: Type
          default: info
        expires_at:
          type: integer
          title: Expires At
        text:
          type: string
          title: Text
        link:
          anyOf:
          - type: string
          - type: 'null'
          title: Link
      type: object
      required:
      - expires_at
      - text
      title: UserNews
    PublicSubscriptionInfoSchema:
      properties:
        product_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Id
        payment_frequency_interval:
          type: string
          title: Payment Frequency Interval
        status:
          type: string
          title: Status
        created_at:
          type: integer
          title: Created At
        next_billing_date:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Billing Date
        previous_billing_date:
          anyOf:
          - type: integer
          - type: 'null'
          title: Previous Billing Date
        cancelled_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cancelled At
        cancel_at_next_billing_date:
          type: boolean
          title: Cancel At Next Billing Date
      type: object
      required:
      - payment_frequency_interval
      - status
      - created_at
      - cancel_at_next_billing_date
      title: PublicSubscriptionInfoSchema
      description: Subscription details exposed via Public API (no internal billing ids).
  securitySchemes:
    Bearer:
      type: http
      description: API key as Bearer token, or x402 PAYMENT-SIGNATURE for agent credits
      scheme: bearer