---
title: "Select the agent-led entry surface or the browser fallback."
method: POST
path: "/v1/workspaces/{workspaceId}/onboarding/agent-state/start"
---

# Select the agent-led entry surface or the browser fallback.

`POST /v1/workspaces/{workspaceId}/onboarding/agent-state/start`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/onboarding/agent-state/start`
- Auth: HTTP bearer

## Request body

- object
  - `entry_surface` 'codex' | 'chatgpt' | 'claude' | 'grok' | 'other_agent' | 'browser', required
  - `client_name` string

## Response `200`

Journey started or resumed.

- object
  - `data` AgentOnboardingState, required
    - `workspace_id` string, uuid, required
    - `status` 'choose_agent' | 'discovering' | 'planning' | 'implementing' | 'validating' | 'ready' | 'complete', required
    - `entry_surface` 'codex' | 'chatgpt' | 'claude' | 'grok' | 'other_agent' | 'browser' | 'null', nullable, required
    - `agent_status` 'not_connected' | 'connecting' | 'connected' | 'browser_only', required
    - `agent_client_name` string, nullable, required
    - `domain_choice` 'undecided' | 'company_domain' | 'no_domain', required
    - `company_domain` string, nullable, required
    - `domain_chosen_at` string, date-time, nullable, required
    - `business_context` object, required
    - `opportunity_plan` object[], required
    - `implementation_summary` object, required
    - `validation_summary` object, required
    - `journey_metadata` object, required
    - `context_reviewed_at` string, date-time, nullable, required
    - `plan_proposed_at` string, date-time, nullable, required
    - `plan_approved_at` string, date-time, nullable, required
    - `completed_at` string, date-time, nullable, required
    - `version` integer, required
    - `updated_at` string, date-time, required
    - `domain_discovery` WorkspaceDomainDiscovery, required
      - `domain` string, required
      - `scan_status` 'complete' | 'partial' | 'failed', required
      - `company` CompanyContextDiscovery, required
        - `domain` string, required
        - `website_url` string, uri, nullable, required
        - `website_status` 'available' | 'missing' | 'blocked' | 'error', required
        - `company_name` string, required
        - `summary` string, required
        - `audience` string, required
        - `offerings` string[], required
        - `logo_url` string, uri, nullable, required
        - `favicon_url` string, uri, nullable, required
        - `visual_identity` CompanyVisualIdentity, required
          - `colors` string[], required
          - `fonts` string[], required
          - `tone` string[], required
          - `source_confidence` 'high' | 'medium' | 'low', required
          - `hero_image_url` string, uri
          - `palette` object[], required
            - `value` string, required
            - `role` 'primary' | 'accent' | 'background' | 'surface' | 'text' | 'other', required
            - `name` string, required
          - `typography` object[], required
            - `family` string, required
            - `role` 'heading' | 'body' | 'mono' | 'other', required
            - `weights` integer[], required
          - `assets` object[], required
            - `url` string, uri, required
            - `kind` 'logo' | 'wordmark' | 'favicon' | 'hero', required
            - `source` string, required
          - `brand_summary` string, required
          - `imagery_style` string[], required
        - `source_snapshot` object, required
      - `dns_signals` DnsSignal[], required
        - `name` string, required
        - `type` 'MX' | 'TXT' | 'CNAME' | 'NS', required
        - `value` string, required
        - `ttl` integer, required
      - `dns_provider` DnsProviderDetection, required
        - `key` string, required
        - `name` string, required
        - `confidence` 'high' | 'medium' | 'low', required
        - `dashboard_url` string, uri, required
        - `evidence` DnsSignal[], required
          - `name` string, required
          - `type` 'MX' | 'TXT' | 'CNAME' | 'NS', required
          - `value` string, required
          - `ttl` integer, required
      - `provider_detections` ProviderDetection[], required
        - `key` string, required
        - `name` string, required
        - `categories` string[], required
        - `confidence` 'high' | 'medium' | 'low', required
        - `evidence` DnsSignal[], required
          - `name` string, required
          - `type` 'MX' | 'TXT' | 'CNAME' | 'NS', required
          - `value` string, required
          - `ttl` integer, required
      - `capability_summary` DiscoveryCapability[], required
        - `kind` 'work_mailbox' | 'transactional' | 'marketing' | 'deliverability', required
        - `label` string, required
        - `status` 'detected' | 'missing' | 'needs_review', required
        - `provider_keys` string[], required
        - `recommendation` 'connect' | 'setup_banger' | 'review', required
      - `recommended_connections` SetupConnectionRecommendation[], required
        - `key` string, required
        - `name` string, required
        - `category` 'email' | 'customer' | 'product' | 'work' | 'data', required
        - `priority` 'required' | 'recommended', required
        - `reason` string, required
        - `source` 'dns' | 'business_context' | 'opportunity_plan' | 'banger_recommendation', required
        - `setup_mode` 'oauth' | 'secure_credentials', required
        - `available` boolean, required
        - `provider_key` string
        - `evidence` DnsSignal[], required
          - `name` string, required
          - `type` 'MX' | 'TXT' | 'CNAME' | 'NS', required
          - `value` string, required
          - `ttl` integer, required
      - `connection_plan` DiscoveryConnectionPlanItem[], required
        - `capability` 'work_mailbox' | 'transactional' | 'marketing' | 'deliverability', required
        - `provider_key` string
        - `action` 'connect' | 'setup_banger' | 'review', required
        - `domain` string
      - `limitations` string[], required
      - `scanned_at` string, date-time, required
      - `confirmed_at` string, date-time, nullable, required
    - `recommended_connections` SetupConnectionRecommendation[], required
      - `key` string, required
      - `name` string, required
      - `category` 'email' | 'customer' | 'product' | 'work' | 'data', required
      - `priority` 'required' | 'recommended', required
      - `reason` string, required
      - `source` 'dns' | 'business_context' | 'opportunity_plan' | 'banger_recommendation', required
      - `setup_mode` 'oauth' | 'secure_credentials', required
      - `available` boolean, required
      - `provider_key` string
      - `evidence` DnsSignal[], required
        - `name` string, required
        - `type` 'MX' | 'TXT' | 'CNAME' | 'NS', required
        - `value` string, required
        - `ttl` integer, required
    - `domain_bundle` object, nullable, required
    - `growth` object, required
    - `activation` AgentActivationState, required
      - `mode` 'hosted' | 'company_domain' | 'starter', required
      - `status` 'hosted_mailbox_required' | 'hosted_mailbox_proving' | 'hosted_mailbox_ready' | 'needs_context' | 'needs_provisioning' | 'provisioning' | 'dns_required' | 'ready_for_proof' | 'proving' | 'activated' | 'starter_required' | 'starter_proving' | 'starter_ready', required
      - `domain` string, nullable, required
      - `sending_domain_id` string, uuid, nullable, required
      - `mailbox_id` string, uuid, nullable, required
      - `mailbox_address` string, email, nullable, required
      - `exact_dns_records` NativeSendingDnsRecord[], required
        - `id` string, uuid, required
        - `lane_id` string, uuid, required
        - `provider` 'banger' | 'resend', required
        - `purpose` string, required
        - `type` 'TXT' | 'MX' | 'CNAME', required
        - `name` string, required
        - `value` string, required
        - `priority` integer, nullable, required
        - `required` boolean, required
        - `status` 'pending' | 'verified' | 'error', required
        - `provider_status` 'pending' | 'verified' | 'error' | 'not_applicable', required
        - `first_observed_at` string, date-time, nullable, required
        - `last_checked_at` string, date-time, nullable, required
        - `error` object, required
        - `provider_reference` string, nullable, required
      - `checkpoints` AgentActivationCheckpoint[], required
        - `key` 'domain' | 'provider' | 'infrastructure' | 'dns' | 'mailbox' | 'product' | 'broadcast', required
        - `label` string, required
        - `status` 'pending' | 'working' | 'action_required' | 'verified', required
        - `detail` string, required
      - `lanes` object, required
        - `mailbox` AgentActivationLane, required
          - `status` 'pending' | 'working' | 'action_required' | 'verified', required
          - `detail` string, required
        - `transactional` AgentActivationLane, required
          - `status` 'pending' | 'working' | 'action_required' | 'verified', required
          - `detail` string, required
        - `marketing` AgentActivationLane, required
          - `status` 'pending' | 'working' | 'action_required' | 'verified', required
          - `detail` string, required
      - `proof` union, required
        - StarterMailboxProof
          - `proof_id` string, uuid, required
          - `mailbox_id` string, uuid, required
          - `mailbox_address` string, email, required
          - `command_id` string, uuid, required
          - `phase` 'sending' | 'sent' | 'received' | 'checked' | 'failed', required
          - `send_complete` boolean, required
          - `receive_complete` boolean, required
          - `round_trip_check_complete` boolean, required
          - `agent_check_complete` boolean, required
          - `complete` boolean, required
          - `expected_subject` string, required
          - `expected_body_text` string, required
          - `received_message_id` string, uuid
          - `received_thread_id` string, uuid
          - `received_subject` string
          - `received_body_text` string
          - `received_at` string, date-time
          - `agent_label` string
          - `agent_suggested_action` string
          - `error_code` string
          - `replayed` boolean, required
        - DomainInfrastructureProof
          - `proof_id` string, uuid, required
          - `domain_id` string, uuid, required
          - `native_domain_id` string, uuid, required
          - `mailbox_id` string, uuid, required
          - `mailbox_address` string, email, required
          - `transactional_send_intent_id` string, uuid
          - `marketing_send_intent_id` string, uuid
          - `transactional_subject` string, required
          - `marketing_subject` string, required
          - `phase` 'sending' | 'receiving' | 'received' | 'checked' | 'failed', required
          - `send_complete` boolean, required
          - `transactional_received` boolean, required
          - `marketing_received` boolean, required
          - `receive_complete` boolean, required
          - `agent_check_complete` boolean, required
          - `complete` boolean, required
          - `error_code` string
          - `replayed` boolean, required
      - `overall_ready` boolean, required
      - `production_ready` boolean, required
    - `completed` boolean, required
    - `pending` boolean, required
    - `next_action` 'choose_agent' | 'provision_hosted_mailbox' | 'send_aha_1' | 'wait_for_aha_1' | 'offer_custom_domain' | 'review_domain_bundle' | 'provision_domain_bundle' | 'wait_for_dns_records' | 'ask_computer_use_permission' | 'configure_dns_with_computer_use' | 'present_manual_dns_instructions' | 'wait_for_dns_propagation' | 'send_aha_2' | 'wait_for_aha_2' | 'create_starter_mailbox' | 'run_starter_proof' | 'wait_for_starter_proof' | 'collect_business_context' | 'build_lifecycle_map' | 'review_growth_system' | 'connect_required_services' | 'explain_persistent_mcp' | 'offer_autopilot' | 'activate_autopilot' | 'validate' | 'complete' | 'open_dashboard', required
    - `action_required` object, required
      - `type` string, required
      - `required` boolean, required
      - `action` 'choose_agent' | 'provision_hosted_mailbox' | 'send_aha_1' | 'wait_for_aha_1' | 'offer_custom_domain' | 'review_domain_bundle' | 'provision_domain_bundle' | 'wait_for_dns_records' | 'ask_computer_use_permission' | 'configure_dns_with_computer_use' | 'present_manual_dns_instructions' | 'wait_for_dns_propagation' | 'send_aha_2' | 'wait_for_aha_2' | 'create_starter_mailbox' | 'run_starter_proof' | 'wait_for_starter_proof' | 'collect_business_context' | 'build_lifecycle_map' | 'review_growth_system' | 'connect_required_services' | 'explain_persistent_mcp' | 'offer_autopilot' | 'activate_autopilot' | 'validate' | 'complete' | 'open_dashboard', required
      - `url` string, uri, nullable, required
      - `instructions` string, nullable, required
    - `secure_url` string, uri, nullable, required
    - `mcp_url` string, uri, required
    - `dashboard_url` string, uri, required

---

[API](https://skmtc.dev/bangermail/apis/banger-api.md) · [All operations](https://skmtc.dev/bangermail/apis/banger-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bangermail/apis/banger-api/revisions/a149909267f9?raw)