> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete workspace onboarding

> Requires personalized_onboarding. Read the current revision and catalogs before saving.



## OpenAPI

````yaml /openapi.yaml post /workspaces/{workspace}/onboarding/complete
openapi: 3.1.0
info:
  title: Contact Button API
  version: 1.0.0-rc.1
  description: >
    API-first management and public agent actions for Contact Buttons and
    button.contact pages.

    Describes the November 16, 2026 release-candidate source; feature
    availability is environment-specific.

    API v1 is the public contract. Existing private legacy API and browser
    workflows remain supported.

    MCP OAuth access tokens are audience-bound to /mcp and are not REST
    credentials.

    See /reference/api-surfaces for the interface inventory and rollout
    boundaries.
  contact:
    name: Contact Button
    url: https://learn.contactbutton.com
servers:
  - url: https://api.contactbutton.com/v1
    description: Production (canonical)
  - url: https://app.contactbutton.com/v1
    description: Backwards-compatible application-domain alias
security:
  - bearerAuth: []
tags:
  - name: Onboarding
    description: Human-verified agent onboarding.
  - name: Workspaces
  - name: Team
  - name: Pages
  - name: Agents
    description: Workspace Agent profile and behavior configuration.
  - name: Domains
  - name: Buttons
  - name: Forms
  - name: Surveys
  - name: Apps
  - name: Knowledge
  - name: Booking
  - name: Telephony
    description: >-
      Bring-your-own-Telnyx setup, call flows, phone numbers, and voice
      interactions.
  - name: Reviews
    description: >-
      Send consented review requests through workspace-owned email, SMS, and
      WhatsApp channels.
  - name: Commerce
  - name: Conversations
    description: >-
      Contact-centric threads and messages across chat, email, WhatsApp, and
      forms.
  - name: Engagement inbox
  - name: Public actions
    description: Public, rate-limited actions that may require human confirmation.
paths:
  /workspaces/{workspace}/onboarding/complete:
    post:
      tags:
        - Onboarding
      summary: Complete workspace onboarding
      description: >-
        Requires personalized_onboarding. Read the current revision and catalogs
        before saving.
      operationId: completeWorkspaceOnboarding
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingInput'
      responses:
        '200':
          $ref: '#/components/responses/Data'
        '404':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
components:
  parameters:
    WorkspaceId:
      name: workspace
      in: path
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional 8–120 character key for replayable mutations. Send the exact
        same method, URI, and body on retries; receipts expire after 24 hours.
      schema:
        type: string
        minLength: 8
        maxLength: 120
  schemas:
    OnboardingInput:
      type: object
      required:
        - revision
        - step
        - business
        - interests
        - style
      properties:
        revision:
          type: integer
          minimum: 0
        step:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 7
        template:
          type:
            - string
            - 'null'
          description: A recipe key from the current onboarding catalog.
        business:
          type: object
          required:
            - url
          properties:
            name:
              type:
                - string
                - 'null'
              maxLength: 150
            url:
              type: string
              format: uri
              maxLength: 2048
            maps_url:
              type:
                - string
                - 'null'
              format: uri
            phone:
              type:
                - string
                - 'null'
              maxLength: 40
            email:
              type:
                - string
                - 'null'
              format: email
            address:
              type:
                - string
                - 'null'
              maxLength: 500
            hours:
              type:
                - string
                - 'null'
              maxLength: 1000
        interests:
          type: object
          description: >-
            Keys from the returned tool catalog; each value is interested,
            later, or no.
          additionalProperties:
            type: string
            enum:
              - interested
              - later
              - 'no'
        widgets:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            type: string
            maxLength: 100
          description: >-
            Active widget slugs from the catalog. Required unless derived from
            widget_drafts; selection steps require at least one.
        widget_drafts:
          type: array
          maxItems: 50
          items:
            type: object
            required:
              - type
              - selected
            properties:
              type:
                type: string
                maxLength: 100
              name:
                type:
                  - string
                  - 'null'
                maxLength: 255
              selected:
                type: boolean
        tool_order:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
        style:
          type: object
          required:
            - layout
            - colors
            - primary
            - secondary
            - icons
          properties:
            layout:
              type: string
              enum:
                - stacked_buttons
                - columns
                - rows
                - floating
                - single_app
                - messenger
            colors:
              type: string
              enum:
                - default
                - brand
                - gradient
            primary:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            secondary:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            icons:
              type: string
              enum:
                - light
                - regular
                - solid
            header_enabled:
              type: boolean
            header_show_status:
              type: boolean
            menu_show_arrow:
              type: boolean
            tabbed_menu:
              type: boolean
            menu_style:
              type: string
              enum:
                - classic
                - modern
            menu_icon_position:
              type: string
              enum:
                - left
                - right
                - none
            text:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            header_background_color:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            header_text_color:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            footer_background_color:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            footer_text_color:
              type: string
              pattern: ^#[a-fA-F0-9]{6}$
            header_title:
              type:
                - string
                - 'null'
              maxLength: 150
            header_subtitle:
              type:
                - string
                - 'null'
              maxLength: 500
            footer_tabs:
              type: array
              maxItems: 3
              description: >-
                Two or three tabs are required when completing a supported
                tabbed layout. App destinations must reference included widgets.
              items:
                type: object
                required:
                  - id
                  - icon
                  - destination
                properties:
                  id:
                    type: string
                    format: uuid
                  label:
                    type:
                      - string
                      - 'null'
                    maxLength: 40
                  icon:
                    type: string
                    description: A supported Button panel icon key.
                  destination:
                    type: object
                    required:
                      - type
                    properties:
                      type:
                        type: string
                        enum:
                          - view
                          - app
                      view:
                        type: string
                        enum:
                          - navigation_root
                      widget:
                        type:
                          - string
                          - 'null'
                        maxLength: 100
      description: >-
        Read onboarding first and send its current revision. Optional style
        settings follow the Button editor, including header and footer tabs.
        Stale revisions return 409. Completion may create draft resources;
        inspect returned state.
      anyOf:
        - required:
            - widgets
        - required:
            - widget_drafts
    DataResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data: {}
        meta:
          type: object
          properties:
            request_id:
              type: string
            next_cursor:
              type:
                - string
                - 'null'
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - code
        - detail
        - resolution
        - instance
        - request_id
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: Stable machine-readable error code.
        detail:
          type: string
        resolution:
          type: string
          description: Safe next step an agent or developer can take.
        instance:
          type: string
        request_id:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  responses:
    Data:
      description: Successful data envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataResponse'
    Problem:
      description: RFC 9457-style problem details.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum personal access token
      description: >
        A Contact Button scoped bearer key. Send `Authorization: Bearer
        <token>`.

        Token abilities are enforced independently of workspace membership; both
        checks must pass.

        REST requires a Sanctum API key. Separately, interactive MCP clients can
        use registered

        OAuth applications with PKCE and audience-bound workspace grants; those
        tokens are not REST credentials.
      x-contact-button-token-abilities:
        workspaces:read: Read workspaces, teams, domains, settings, and connections.
        workspaces:write: >-
          Create and manage workspaces, teams, domains, settings, and
          connections.
        content:read: Read buttons, forms, lists, pages, booking types, and knowledge.
        content:write: Create, update, publish, and remove content.
        engagements:read: >-
          Read submissions, subscribers, bookings, callbacks, calls, reviews,
          and conversations.
        engagements:manage: Reply to and manage engagement records.
        actions:request: Request protected actions that can still require human confirmation.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.