CHNLSYNC Customer Intake API

openapi: 3.2.0
info:
  title: Chnlsync Com Customer Intake API
  version: 0.1.0
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged customer-intake across 2 of this provider''s published API definitions: chnlsync-com-openapi.json, chnlsync-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.chnlsync.dev
  description: CHNLSYNC API host advertised in https://chnlsync.com/llms.txt (servers[] absent in the served spec; added here)
tags:
- name: customer-intake
paths:
  /api/v1/customer/intake/status:
    get:
      tags:
      - customer-intake
      summary: Get Intake Status
      description: 'Report whether public intake is open, so callers can probe up front.


        Deliberately NOT gated on the intake flag (it never 404s): the dashboard

        uses it to render the closed state before showing the form instead of

        after a doomed submit. Exposes only the flag value — no data, no writes.'
      operationId: get_intake_status_api_v1_customer_intake_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerIntakeStatusResponse'
  /api/v1/customer/intake:
    post:
      tags:
      - customer-intake
      summary: Post Intake
      description: Create a provisional intake workspace from the public form.
      operationId: post_intake_api_v1_customer_intake_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerIntakeCreateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerIntakeCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/intake/chat:
    post:
      tags:
      - customer-intake
      summary: Post Intake Chat
      description: Run one anonymous advisor turn against a provisional workspace.
      operationId: post_intake_chat_api_v1_customer_intake_chat_post
      parameters:
      - name: X-Intake-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Intake-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerIntakeChatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/customer/intake/claim:
    post:
      tags:
      - customer-intake
      summary: Post Intake Claim
      description: 'Merge a provisional workspace into the signed-in Clerk tenant.


        Deliberately NOT gated on the intake flag: links already handed out

        must stay claimable even if new intake closes. Auth is the signed-in

        Clerk principal; possession of the claim credential is the ownership

        proof.'
      operationId: post_intake_claim_api_v1_customer_intake_claim_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerIntakeClaimRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerIntakeClaimResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    CustomerIntakeAttribution:
      properties:
        source:
          type: string
          enum:
          - google
          - bing
          - duckduckgo
          - linkedin
          - facebook
          - instagram
          - x
          - chatgpt
          - perplexity
          - newsletter
          - smartlead
          - direct
          - other_referral
          - unknown
          title: Source
          default: unknown
        medium:
          type: string
          enum:
          - organic
          - cpc
          - paid_social
          - social
          - email
          - referral
          - none
          - unknown
          title: Medium
          default: unknown
        landing_page:
          type: string
          maxLength: 180
          title: Landing Page
          default: /start
        campaign_code:
          anyOf:
          - type: string
            enum:
            - a1
            - a2
            - b1
          - type: 'null'
          title: Campaign Code
      type: object
      title: CustomerIntakeAttribution
      description: 'Bounded acquisition metadata, never evidence of buyer qualification.


        Malformed analytics values fall back safely instead of blocking intake.

        Extra fields are ignored so raw URLs, query strings, contact details, and

        transcripts cannot enter the stored attribution object.'
    CustomerIntakeClaimResponse:
      properties:
        tenant:
          $ref: '#/components/schemas/CustomerTenantRead'
        mode:
          type: string
          enum:
          - rekeyed
          - merged
          title: Mode
      type: object
      required:
      - tenant
      - mode
      title: CustomerIntakeClaimResponse
      description: Result of merging a provisional workspace into a Clerk tenant.
    EnvironmentFactCategory:
      type: string
      enum:
      - company
      - connectivity
      - ucaas
      - ccaas
      - cpaas
      - security
      - cloud
      - colo
      - cx_ai
      - pro_services
      - sase
      - vendor
      - contract
      - pain_point
      - timeline
      - budget
      - other
      title: EnvironmentFactCategory
      description: Normalized buckets for customer IT environment memory.
    CustomerIntakeClaimRequest:
      properties:
        intake_id:
          type: string
          format: uuid
          title: Intake Id
        intake_token:
          type: string
          maxLength: 255
          minLength: 1
          title: Intake Token
      type: object
      required:
      - intake_id
      - intake_token
      title: CustomerIntakeClaimRequest
      description: Authenticated claim of a provisional intake workspace (D2.2).
    CustomerChatResponse:
      properties:
        assistant_message:
          type: string
          title: Assistant Message
        user_message_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: User Message Id
        assistant_message_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Assistant Message Id
          description: Persisted id of the assistant reply, used by the portal for message feedback. None for refusal/over-cap turns that persist no assistant row.
        follow_up_questions:
          items:
            type: string
          type: array
          maxItems: 4
          title: Follow Up Questions
          description: Buyer-visible suggested follow-up questions. The service sets this explicitly on every new response; the default preserves compatibility with older cached/client payloads.
        conversation_id:
          type: string
          format: uuid
          title: Conversation Id
        environment_deltas:
          items:
            $ref: '#/components/schemas/EnvironmentFactRead'
          type: array
          title: Environment Deltas
        case_draft:
          anyOf:
          - $ref: '#/components/schemas/CaseDraft'
          - type: 'null'
        citations:
          items:
            $ref: '#/components/schemas/Citation'
          type: array
          title: Citations
        review_status:
          anyOf:
          - $ref: '#/components/schemas/CustomerCaseStatus'
          - type: 'null'
        buyer_visible_lanes:
          items:
            type: string
          type: array
          title: Buyer Visible Lanes
        advisor_mode:
          type: string
          enum:
          - llm
          - deterministic_fallback
          - unavailable
          title: Advisor Mode
          description: Advisor runtime mode. The service sets this explicitly on every new response; the default preserves compatibility with older cached/client payloads.
          default: deterministic_fallback
        memory_updated:
          type: boolean
          title: Memory Updated
          description: Whether this turn wrote tenant memory. The service sets this explicitly on every new response; the default preserves compatibility with older cached/client payloads.
          default: false
        review_prep_requested:
          type: boolean
          title: Review Prep Requested
          description: True when this turn flipped the active case into CHNLSYNC review because the buyer agreed to the advisor's review offer. Signals the router to enqueue review prep (source='advisor_chat') for the case carried in ``case_draft.case_id``.
          default: false
        review_booking:
          anyOf:
          - $ref: '#/components/schemas/CaseBookingRead'
          - type: 'null'
          description: Booking CTA attached to the escalation turn (only when ``review_prep_requested`` is True and customer_escalation_booking_enabled is on) so the portal can offer the review-call scheduler at the handoff moment. The URL is operator-configured (settings.cal_com_booking_url) — never model output.
        internal_supplier_notes_hidden:
          type: boolean
          const: true
          title: Internal Supplier Notes Hidden
          default: true
      type: object
      required:
      - assistant_message
      - conversation_id
      - environment_deltas
      - case_draft
      - citations
      - review_status
      - buyer_visible_lanes
      title: CustomerChatResponse
      description: Public advisor response shape for the customer portal.
    CustomerTenantRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
        clerk_org_id:
          type: string
          title: Clerk Org Id
        status:
          type: string
          title: Status
      type: object
      required:
      - id
      - name
      - domain
      - clerk_org_id
      - status
      title: CustomerTenantRead
      description: Customer tenant details visible to members of that tenant.
    CaseDraft:
      properties:
        case_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Case Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        readiness_score:
          type: integer
          title: Readiness Score
      type: object
      required:
      - readiness_score
      title: CaseDraft
      description: Case draft details emitted by an advisor turn.
    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
    CustomerCaseStatus:
      type: string
      enum:
      - draft
      - chnlsync_reviewing
      - needs_info
      - supplier_path_drafted
      - ready_for_call
      - closed
      title: CustomerCaseStatus
      description: Human-gated customer advisory case lifecycle.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CustomerIntakeCreateRequest:
      properties:
        company_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Company Name
        domain:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Domain
        site_count:
          anyOf:
          - type: integer
            maximum: 10000.0
            minimum: 1.0
          - type: 'null'
          title: Site Count
        current_providers:
          items:
            type: string
          type: array
          maxItems: 20
          title: Current Providers
        contract_end_dates:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Contract End Dates
        pain:
          type: string
          maxLength: 4000
          minLength: 1
          title: Pain
        state:
          anyOf:
          - type: string
            pattern: ^[A-Z]{2}$
          - type: 'null'
          title: State
        source:
          anyOf:
          - type: string
            maxLength: 64
            minLength: 1
            pattern: ^[a-z0-9_:-]+$
          - type: 'null'
          title: Source
        attribution:
          anyOf:
          - $ref: '#/components/schemas/CustomerIntakeAttribution'
          - type: 'null'
      type: object
      required:
      - company_name
      - pain
      title: CustomerIntakeCreateRequest
      description: Structured answers from the public intake form (roadmap D2.1).
    EnvironmentFactRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        category:
          $ref: '#/components/schemas/EnvironmentFactCategory'
        label:
          type: string
          title: Label
        value:
          type: string
          title: Value
        source_type:
          type: string
          title: Source Type
        source_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Source Id
        source_label:
          type: string
          title: Source Label
        confidence:
          type: number
          title: Confidence
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - category
      - label
      - value
      - source_type
      - source_label
      - confidence
      - created_at
      - updated_at
      title: EnvironmentFactRead
      description: Buyer-visible environment fact with provenance.
    CaseBookingRead:
      properties:
        booking_url:
          type: string
          title: Booking Url
        clicked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Clicked At
      type: object
      required:
      - booking_url
      title: CaseBookingRead
      description: Buyer-visible booking call-to-action for an approved case (D2.5).
    CustomerIntakeCreateResponse:
      properties:
        intake_id:
          type: string
          format: uuid
          title: Intake Id
        intake_token:
          type: string
          title: Intake Token
        claim_path:
          type: string
          title: Claim Path
        environment_summary:
          type: string
          title: Environment Summary
        missing_info:
          items:
            type: string
          type: array
          title: Missing Info
        fact_count:
          type: integer
          title: Fact Count
          default: 0
      type: object
      required:
      - intake_id
      - intake_token
      - claim_path
      - environment_summary
      title: CustomerIntakeCreateResponse
      description: Provisional workspace handle returned exactly once at intake.
    Citation:
      properties:
        source_type:
          type: string
          title: Source Type
        source_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Source Id
        label:
          type: string
          title: Label
        evidence_grade:
          anyOf:
          - type: string
            enum:
            - your_data
            - vetted_catalog
            - industry_knowledge
          - type: 'null'
          title: Evidence Grade
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        as_of:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: As Of
      type: object
      required:
      - source_type
      - label
      title: Citation
      description: 'Source citation used by a customer advisor answer.


        Evidence-grading fields (roadmap 1.3) are optional so citations persisted

        on messages before the upgrade still parse from stored JSON.'
    CustomerIntakeChatRequest:
      properties:
        intake_id:
          type: string
          format: uuid
          title: Intake Id
        message:
          type: string
          maxLength: 8000
          minLength: 1
          title: Message
        conversation_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Conversation Id
      type: object
      required:
      - intake_id
      - message
      title: CustomerIntakeChatRequest
      description: Anonymous advisor chat turn scoped to a provisional intake.
    CustomerIntakeStatusResponse:
      properties:
        enabled:
          type: boolean
          title: Enabled
      type: object
      required:
      - enabled
      title: CustomerIntakeStatusResponse
      description: Public availability of the anonymous intake surface.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Agent-API-Key
x-refined-from:
- chnlsync-com-openapi.json
- chnlsync-com-openapi.yml