Clickwise Onboarding API

openapi: 3.2.0
info:
  title: Clickwise Panel v2 Onboarding API
  version: 2.0.0
  description: 'Public endpoints of Clickwise: deals, program news, monetization links, partner onboarding, catalog statistics and samples, site widgets and product feeds. Endpoints that need an account are documented in the full schema, served to authenticated accounts at /api/v1/openapi-full.json.


    See also: /llms.txt (single-file LLM brief) and the MCP server at /api/v1/mcp/.'
  contact:
    name: Clickwise
    email: hello@clickwise.net
    url: https://clickwise.net/
  license:
    name: Proprietary
servers:
- url: https://partners.clickwise.net
  description: Host the spec is served from and that llms.txt names for every /api/v1 endpoint (servers[] absent in the published spec)
tags:
- name: Onboarding
paths:
  /api/v1/onboarding/affiliate/:
    post:
      operationId: onboarding_affiliate_create
      description: 'Minimum: `email` (or `username`) + how you promote (`website` or social handle + category). The AI evaluates instantly and interviews via /respond/ if it needs more. Fiscal/payout data is NOT needed here — it is requested at first payout.'
      summary: Start an affiliate onboarding application (public, AI-driven)
      tags:
      - Onboarding
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AffiliateOnboardingStartRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AffiliateOnboardingStartRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AffiliateOnboardingStartRequest'
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
        '201':
          description: No response body
        '202':
          description: No response body
        '400':
          description: No response body
        '404':
          description: No response body
  /api/v1/onboarding/affiliate/{id}/:
    get:
      operationId: onboarding_affiliate_retrieve
      description: GET state + conversation. Secret, owner, or full-read role only.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Onboarding
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding affiliate retrieve
      x-summary-source: derived
  /api/v1/onboarding/affiliate/{id}/respond/:
    post:
      operationId: onboarding_affiliate_respond_create
      description: POST {message} → next turn from the agent. Secret, owner, or full-read.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Onboarding
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding affiliate respond create
      x-summary-source: derived
  /api/v1/onboarding/merchant/:
    post:
      operationId: onboarding_merchant_create
      description: 'Frictionless start: a free-text `message` OR `company_name`/`website` is enough — the AI collects the rest (including email) conversationally via /respond/. Returns the application state + a one-time `access_secret` to authenticate follow-ups (header `X-Application-Secret`).'
      summary: Start a merchant onboarding application (public, AI-driven)
      tags:
      - Onboarding
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantOnboardingStartRequest'
            examples:
              MinimalStart:
                value:
                  contact_email: owner@store.com
                  website: https://store.com
                  lang: en
                summary: Minimal start
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MerchantOnboardingStartRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MerchantOnboardingStartRequest'
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '201':
          description: No response body
        '400':
          description: No response body
        '409':
          description: No response body
  /api/v1/onboarding/merchant/{id}/:
    get:
      operationId: onboarding_merchant_retrieve
      description: 'Public — anonymous candidate can read with access_secret; managers always.

        Authenticated email-matching candidates can also read.'
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Onboarding
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding merchant retrieve
      x-summary-source: derived
    post:
      operationId: onboarding_merchant_create_2
      description: Explicit checkbox changes, independent of chat/AI approval.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Onboarding
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding merchant create 2
      x-summary-source: derived
  /api/v1/onboarding/merchant/{id}/credentials/:
    post:
      operationId: onboarding_merchant_credentials_create
      description: 'get_merchant_credentials: Returns a merchant API token only if the account has none yet. If one exists, it answers 409 and explains where the account holder can copy it. It never reveals an existing token.'
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Onboarding
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding merchant credentials create
      x-summary-source: derived
  /api/v1/onboarding/merchant/{id}/respond/:
    post:
      operationId: onboarding_merchant_respond_create
      description: 'Same auth as Detail — secret OR manager OR email-match.


        Every reply is a Gemini call, so it is throttled per real client IP and

        per application on top of the interview''s own ``max_turns``. The

        per-application bucket is charged only once the caller has proved it may

        reply: charged in ``initial()`` it let anyone freeze a chat by POSTing

        to its sequential ``pk`` without the secret.'
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Onboarding
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding merchant respond create
      x-summary-source: derived
  /api/v1/onboarding/merchant/programs/:
    post:
      operationId: onboarding_merchant_programs_create
      description: 'Frictionless start: a free-text `message` OR `company_name`/`website` is enough — the AI collects the rest (including email) conversationally via /respond/. Returns the application state + a one-time `access_secret` to authenticate follow-ups (header `X-Application-Secret`).'
      summary: Start a merchant onboarding application (public, AI-driven)
      tags:
      - Onboarding
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantOnboardingStartRequest'
            examples:
              MinimalStart:
                value:
                  contact_email: owner@store.com
                  website: https://store.com
                  lang: en
                summary: Minimal start
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MerchantOnboardingStartRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MerchantOnboardingStartRequest'
      security:
      - cookieAuth: []
      - apiKeyAuth: []
      - tokenAuth: []
      - {}
      responses:
        '201':
          description: No response body
        '400':
          description: No response body
        '409':
          description: No response body
  /api/v1/onboarding/merchant/test-sale/{token}/:
    get:
      operationId: onboarding_merchant_test_sale_retrieve
      description: Run the signed, expiring assisted canary linked from the email thread.
      parameters:
      - in: path
        name: token
        schema:
          type: string
        required: true
      tags:
      - Onboarding
      security:
      - {}
      responses:
        '200':
          description: No response body
      summary: Onboarding merchant test sale retrieve
      x-summary-source: derived
components:
  schemas:
    MerchantOnboardingStartRequest:
      type: object
      properties:
        contact_email:
          type: string
          format: email
        company_name:
          type: string
        website:
          type: string
          format: uri
        message:
          type: string
          description: 'Free-text: tell us about your store.'
        lang:
          type: string
          description: e.g. en, es; auto-detected if omitted.
        form_started_at:
          type: integer
          description: Browser form start time in epoch milliseconds; required for anonymous browser signup.
        terms_accepted:
          type: boolean
        terms_version:
          type: string
        css_accepted:
          type: boolean
        css_version:
          type: string
        countries:
          type: array
          items:
            type: string
        on_behalf_of:
          type: object
          additionalProperties: {}
          description: 'Full-read/API operators only: email, company and site for the third-party applicant.'
    AffiliateOnboardingStartRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        username:
          type: string
        website:
          type: string
          format: uri
        category:
          type: string
        message:
          type: string
          description: 'Free-text: how will you promote?'
        lang:
          type: string
        phone:
          type: string
        wa_service_opt_in:
          type: boolean
          default: false
        wa_marketing_opt_in:
          type: boolean
          default: false
        application_id:
          type: integer
          description: Application id returned by an earlier retryable response.
        access_secret:
          type: string
          writeOnly: true
          description: Per-application secret returned by an earlier response.
        on_behalf_of:
          type: object
          additionalProperties: {}
          description: 'Full-read/API operators only: email, company and site for the third-party applicant.'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    tokenAuth:
      type: http
      scheme: bearer
externalDocs:
  url: https://clickwise.net/llms.txt
  description: LLM brief
x-servers-source: https://partners.clickwise.net/llms.txt